Skip to content

session-handoff.md

Latest commit

 

History

History
120 lines (94 loc) · 8.43 KB

session-handoff.md

File metadata and controls

120 lines (94 loc) · 8.43 KB

Session Handoff -- Mercur.js

Last Session: 2026-05-15

What Was Accomplished

  1. Lint toolchain migration: ESLint -> oxlint

    • Root package.json lint script switched to oxlint; added oxlint ^1.64.0 devDependency; dropped format and check-types root scripts.
    • Per-package lint scripts updated in packages/admin/package.json (oxlint --max-warnings 0) and apps/admin-test/package.json (oxlint).
    • New .oxlintrc.json at repo root: typescript, react, import, jsx-a11y plugins, correctness=error / suspicious=warn / perf=warn, ignore patterns for dist, build, .next, .turbo, .medusa, .mercur, coverage. react/react-in-jsx-scope disabled (React 17+ JSX automatic runtime).
    • First lint pass: bunx oxlint --quiet reports 0 errors / 1190 warnings across 4390 files.
    • bun.lock regenerated.

  2. Turbo pipeline cleanup

    • turbo.json build.outputs changed from .next/** to dist/**, .medusa/**, !**/cache/**.
    • dev task now declares dependsOn: ["^build"] so dashboards see freshly built upstream packages (needed for the canary.5 dashboard-sdk dedupe fix to actually take effect).

  3. Repository cleanup

    • Removed unused tooling: tools/template-sync/check.ts, tools/template-sync/config.ts.
    • Removed stale meilisearch integration test files: integration-tests/src/api/admin/meilisearch/route.ts, integration-tests/src/api/store/meilisearch/products/search/route.ts, integration-tests/src/api/middlewares.ts.
    • Dropped test:integration:meilisearch script from integration-tests/package.json.
    • Removed superseded docs: docs/seller.md, docs/seller-members.md, docs/subscriptions.md.
    • Removed AGENTS.md (Claude-Code-only project now; see new CLAUDE.md).

  4. Documentation rewrite

    • CLAUDE.md rewritten as a Quick Reference (~284 -> ~101 lines) covering project overview, build/run, project structure, commands, testing, working rules, required artifacts, and Definition of Done.
    • New docs/ARCHITECTURE.md -- system overview, layer diagram (storefront -> client -> API -> core plugin -> Medusa + DB), package responsibilities.
    • New docs/PRODUCT.md -- product description for three audiences (marketplace operators, sellers/vendors, developers/AI agents) plus full feature list (multi-vendor sellers, commissions, payouts, order splitting, etc.).
    • New packages/core/ARCHITECTURE.md -- core plugin internals.

  5. Repo artifacts for agent continuity

    • Created claude-progress.md and this session-handoff.md.

What Remains

  • Run end-to-end verification on the uncommitted refactor. Lint passes (0 errors); build + tests still pending:

    • bun install to refresh the lockfile cleanly.
    • Triage the 1190 oxlint warnings -- decide bulk-fix via bunx oxlint --fix vs. silencing categories in .oxlintrc.json.
    • bun run build -- confirm the turbo.json output-path change does not break package caching or downstream consumers.
    • bun run test:integration:http -- <pattern> on at least one suite (e.g. product) to confirm the meilisearch test removal did not leave dangling Jest references or middleware imports.

  • Docs index check: confirm apps/docs/docs.json (or equivalent Mintlify nav) no longer references the three deleted seller/subscriptions markdown files.

  • Commit strategy: split into two commits when verification passes

    • chore(repo): migrate from eslint to oxlint and drop unused tooling
    • docs: add ARCHITECTURE, PRODUCT, and core/ARCHITECTURE references

Decisions Made

  • oxlint over ESLint -- prioritizing speed of bun run lint in CI; accepting that some custom ESLint rules will not be ported. New baseline is "oxlint clean", not "ESLint clean".
  • dev depends on ^build -- accepts a slower first bun run dev in exchange for upstream packages being available to Vite at runtime. Required for the dashboard-sdk dedupe fix from canary.5 to take effect for consumers running dev from the monorepo root.
  • turbo.json outputs broadened -- dist/** + .medusa/** covers both standard TypeScript builds and Medusa's generated artifacts; !**/cache/** keeps Turbo from caching its own cache.
  • Old seller/subscription markdown removed, not migrated -- they were stale enough that updating in place was worse than rewriting. The new docs/PRODUCT.md covers the same audience needs.
  • CLAUDE.md rewritten as quick-reference, not narrative -- past version mixed CLI usage docs (better suited to apps/docs) with agent guidance. Quick-reference format makes the agent's mandatory startup workflow explicit.

Files Modified

Modified

  • CLAUDE.md -- rewritten as quick reference for Claude Code agents.
  • package.json -- switched lint to oxlint; added oxlint dependency; dropped format + check-types scripts.
  • turbo.json -- build outputs and dev dependency change.
  • bun.lock -- regenerated.
  • apps/admin-test/package.json -- lint script now oxlint.
  • apps/vendor/package.json -- bumped to canary.5 alignment.
  • packages/admin/package.json -- lint script now oxlint --max-warnings 0.
  • packages/dashboard-sdk/package.json -- canary.5 alignment.
  • packages/vendor/package.json -- canary.5 alignment.
  • integration-tests/package.json -- removed test:integration:meilisearch script.

Added

  • .oxlintrc.json -- oxlint configuration.
  • docs/ARCHITECTURE.md -- system architecture doc.
  • docs/PRODUCT.md -- product description doc.
  • packages/core/ARCHITECTURE.md -- core plugin internals.
  • claude-progress.md -- session log + verified state.
  • session-handoff.md -- this file.

Deleted

  • AGENTS.md
  • docs/seller.md
  • docs/seller-members.md
  • docs/subscriptions.md
  • tools/template-sync/check.ts
  • tools/template-sync/config.ts
  • integration-tests/src/api/admin/meilisearch/route.ts
  • integration-tests/src/api/store/meilisearch/products/search/route.ts
  • integration-tests/src/api/middlewares.ts

Diff summary: 19 files changed, +138 / -1040 (plus 4 new untracked files).

Recent Committed Sessions (for context)

  • 2026-05-11 -- PR #919 (a15dc78f): i18n coverage + onboarding extensibility. Expanded vendor pl.json and en.json (+425 / +39 lines). Added useOnboarding hook and new dashboard-sdk types/plugin hook for extensible onboarding. Tightened seller validators. 69 files, +1673 / -277.
  • 2026-05-12 -- canary.1 -> canary.5 fix train:
    • b77c9ce9 fix(vendor): improve PL translations for order statuses/columns
    • e886d5bd fix(vendor): correct thumbnail size in order summary
    • 89370c1f fix(admin): improve PL translations for order statuses/columns
    • c4912156 fix(vendor): translate commission label in order summary
    • 3c4e9ac5 fix(dashboard-sdk): dedupe i18next and react in vite resolve

Blockers

None hard-blocking. Soft risk: oxlint may surface new errors on first run, which could turn this from a clean refactor into a wider follow-up. Triage on first lint run will determine scope.

Known Risks

  • Lint coverage gap -- oxlint does not implement every ESLint rule; some violations previously caught may silently pass. Spot-check against the prior eslint --max-warnings 0 baseline if a regression appears.
  • Turbo cache invalidation -- first build after merge will cold-start every package. Expect a slow first CI run.
  • dev depends on ^build -- changes bun run dev startup cost; if DX feedback is negative, revisit.
  • Docs nav drift -- deleted three markdown files without yet updating the Mintlify navigation. If apps/docs references them, the docs build will fail.

Next Steps

  1. From repo root: bun install -- confirms the lockfile regenerates clean without ESLint left in the graph.
  2. bun run lint -- triage oxlint findings. Fix trivial issues in place; for rules with no clean fix, decide whether to disable in .oxlintrc.json (with reason) or fix the underlying code.
  3. bun run build -- confirm all packages build with the new turbo.json output paths.
  4. bun run test:integration:http -- product (or any one suite) -- confirm Jest still resolves after meilisearch file removal.
  5. Grep apps/docs for references to seller.md, seller-members.md, subscriptions.md; remove or redirect.
  6. Commit in two logical units: chore(repo): migrate from eslint to oxlint and drop unused tooling and docs: add ARCHITECTURE, PRODUCT, and core/ARCHITECTURE references.
  7. Update claude-progress.md Session 3 with the verification evidence and mark next-best-action as "merge / open PR".