From 77d59ee7b1eb904453c82ce14df09482e7f1ded4 Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Sun, 10 May 2026 22:41:36 +0100 Subject: [PATCH] vault backup: 2026-05-10 22:41:36 --- wiki/_master-index.md | 2 +- wiki/concepts/_index.md | 3 + .../active-component-import-verification.md | 50 ++++++++++++++ ...nt-flatcompat-next16-circular-reference.md | 57 +++++++++++++++ .../figma-code-connect-plan-requirements.md | 69 +++++++++++++++++++ wiki/log.md | 11 +++ 6 files changed, 191 insertions(+), 1 deletion(-) create mode 100644 wiki/concepts/active-component-import-verification.md create mode 100644 wiki/concepts/eslint-flatcompat-next16-circular-reference.md create mode 100644 wiki/concepts/figma-code-connect-plan-requirements.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index f1de9ee..3f65d53 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -23,7 +23,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/tech-patterns/_index\|tech-patterns/]] | Recurring tech stacks: FastAPI, React/Vite, Next.js, Azure AD, AI, Box, One2Edit, Redis/Celery, cost-tracker, OMG API | 28 | | [[wiki/architecture/_index\|architecture/]] | Cross-cutting architectural patterns: Docker Compose, multi-agent AI, GCP timeout, RAG, hotfolder, optical-dev deploy, cost-tracker, new-project checklist, troubleshooting playbooks, ADR log, Cloud Run Jobs | 11 | | [[wiki/client-knowledge/_index\|client-knowledge/]] | Per-client notes for Ford, H&M, L'Oréal, Barclays, Ferrero, 3M, BAIC | 7 | -| [[wiki/concepts/_index\|concepts/]] | Atomic knowledge extracted from Claude Code sessions | 174 | +| [[wiki/concepts/_index\|concepts/]] | Atomic knowledge extracted from Claude Code sessions | 177 | | [[wiki/connections/_index\|connections/]] | Cross-cutting insights linking 2+ concepts: FastAPI+Azure AD+Docker trinity, AI→cost-tracker, Apache+Vite basePath, GCP→REST polling, Box+hotfolder, Docker DNS+AdGuard, Celery prefork×faster_whisper memory stacking | 10 | | [[wiki/qa/_index\|qa/]] | Filed answers to queries (saved with `--file-back`) | 0 | | [[wiki/homelab/_index\|homelab/]] | Self-hosted infra: Proxmox install, IOMMU/PCI passthrough, hypervisor setup, budget builds, HP Elitedesk G3, Homarr API + Apps + Boards + Certificates + Integrations + Settings + Tasks + AdGuard + Clock + Docker Stats + Docker Integration + Download Client + Firewall + Proxmox Integration + Radarr + Readarr + Sonarr + Bookmarks + Calendar + Icons + App Widget + Weather + GitHub + Nextcloud + qBittorrent + RSS Feed + Speedtest Tracker + System Health Monitoring + System Resources + Services Map + Media Stack | 43 | diff --git a/wiki/concepts/_index.md b/wiki/concepts/_index.md index 6cbf86c..1443993 100644 --- a/wiki/concepts/_index.md +++ b/wiki/concepts/_index.md @@ -224,5 +224,8 @@ | [[wiki/concepts/secrets-git-history-purge]] | `git-filter-repo --invert-paths --path .env` permanently removes secrets from history; force push required; all clones must be redone | daily/2026-05-09.md | 2026-05-09 | | [[wiki/concepts/payload-cms-push-dev-prod]] | `push: process.env.NODE_ENV === 'development'` — auto-schema in dev, migration-only in prod; `push: false` default silently breaks fresh DB | daily/2026-05-09.md | 2026-05-09 | | [[wiki/concepts/cloudflare-proxied-domain-npm-subpath]] | Cloudflare-only domains have no NPM nginx vhost — Custom Locations fail; solution is a separate subdomain with its own NPM Proxy Host | daily/2026-05-09.md | 2026-05-09 | +| [[wiki/concepts/eslint-flatcompat-next16-circular-reference]] | `FlatCompat` wrapping `eslint-config-next` v16 causes circular reference crash — import nextConfig directly; FlatCompat is redundant for v16+ | daily/2026-05-10.md | 2026-05-10 | +| [[wiki/concepts/active-component-import-verification]] | Grep import chain before editing — Header.tsx vs HeaderClient.tsx lesson; editing the wrong file wastes cycles with no visible change | daily/2026-05-10.md | 2026-05-10 | +| [[wiki/concepts/figma-code-connect-plan-requirements]] | Figma Code Connect: `send_code_connect_mappings` MCP requires Org/Enterprise plan; CLI `figma connect publish` works on all plans | daily/2026-05-10.md | 2026-05-10 | diff --git a/wiki/concepts/active-component-import-verification.md b/wiki/concepts/active-component-import-verification.md new file mode 100644 index 0000000..6295289 --- /dev/null +++ b/wiki/concepts/active-component-import-verification.md @@ -0,0 +1,50 @@ +--- +title: Active Component Import Verification — Check Which File Is Actually Rendered +source: daily/2026-05-10.md +updated: 2026-05-10 +tags: [react, next.js, debugging, workflow] +--- + +# Active Component Import Verification — Check Which File Is Actually Rendered + +## The Pattern + +Before editing a component file, verify it is the one the app actually imports and renders. Editing the wrong file wastes multiple edit cycles with no visible change in the browser. + +## The Bug (Shumiland Case Study) + +A project had two header files: +- `src/components/Header.tsx` — unused legacy file +- `src/components/HeaderClient.tsx` — the actual rendered component + +All edits went to `Header.tsx` because it was found first by glob. The app imports `HeaderClient.tsx` exclusively. The browser never changed. + +## How to Verify Before Editing + +```bash +# Find who imports the component you want to change +grep -r "import.*Header" src/ --include="*.tsx" --include="*.ts" + +# Or trace from the page/layout file downward +grep -r "Header" src/app/ --include="*.tsx" +``` + +In Claude Code, use Grep to check the import chain: +``` +pattern: "import.*Header|from.*Header" +path: src/ +``` + +## Rule + +**When a component name has multiple matching files, always grep for which one is imported before editing.** + +Common patterns that cause this: +- `Header.tsx` vs `HeaderClient.tsx` (React Server Component split) +- `Button.tsx` vs `ButtonBase.tsx` +- `Layout.tsx` vs `RootLayout.tsx` +- `index.tsx` barrel files that re-export a different file + +## Cost of Getting This Wrong + +Each wasted edit cycle = reading the file, editing, checking browser, realizing nothing changed, investigating. In a long context window this compounds quickly and causes false conclusions ("the CSS must be wrong" when the file was never rendered at all). diff --git a/wiki/concepts/eslint-flatcompat-next16-circular-reference.md b/wiki/concepts/eslint-flatcompat-next16-circular-reference.md new file mode 100644 index 0000000..7dcfe08 --- /dev/null +++ b/wiki/concepts/eslint-flatcompat-next16-circular-reference.md @@ -0,0 +1,57 @@ +--- +title: ESLint FlatCompat + eslint-config-next v16 — Circular Reference Crash +source: daily/2026-05-10.md +updated: 2026-05-10 +tags: [eslint, next.js, config, flat-config] +--- + +# ESLint FlatCompat + eslint-config-next v16 — Circular Reference Crash + +## The Problem + +Wrapping `eslint-config-next` with `FlatCompat` from `@eslint/eslintrc` causes a `"circular reference"` crash in ESLint's flat config system. + +``` +Error: Circular reference detected + at FlatCompat.extends (...) +``` + +This blocks the pre-commit hook (or any direct ESLint run) completely. + +## Root Cause + +`eslint-config-next` v16+ already exports native flat config. When `FlatCompat` attempts to wrap it, the config tries to extend itself via the compatibility layer, creating a circular dependency. + +## Fix + +Remove `FlatCompat` entirely. Import `eslint-config-next` directly: + +```js +// eslint.config.mjs — WRONG (pre v16 pattern) +import { FlatCompat } from '@eslint/eslintrc' +const compat = new FlatCompat({ baseDirectory: import.meta.dirname }) +export default [ + ...compat.extends('next/core-web-vitals'), +] + +// eslint.config.mjs — CORRECT (v16+) +import nextConfig from 'eslint-config-next' +export default [ + ...nextConfig, + // project-specific overrides +] +``` + +## Key Points + +- `eslint-config-next` v16 ships flat config natively — `FlatCompat` is not only unnecessary but harmful +- The crash manifests as `"circular reference"` with no indication that the config itself is the culprit +- `next lint` is also removed in Next.js 16 — run `npx eslint .` directly +- Pre-commit ESLint hooks will block all commits until the config is fixed; check ESLint independently before stashing + +## Diagnostic Signal + +``` +TypeError: Cannot read properties of undefined (reading 'circular') +``` +or simply `"circular reference"` in the ESLint output when running against a Next.js 16 project. diff --git a/wiki/concepts/figma-code-connect-plan-requirements.md b/wiki/concepts/figma-code-connect-plan-requirements.md new file mode 100644 index 0000000..958b290 --- /dev/null +++ b/wiki/concepts/figma-code-connect-plan-requirements.md @@ -0,0 +1,69 @@ +--- +title: Figma Code Connect — MCP vs CLI Plan Requirements +source: daily/2026-05-10.md +updated: 2026-05-10 +tags: [figma, code-connect, mcp, cli] +--- + +# Figma Code Connect — MCP vs CLI Plan Requirements + +## Two Approaches + +Figma Code Connect maps Figma components to codebase components so that Dev Mode shows real component code instead of generated CSS. + +### MCP Approach (`send_code_connect_mappings`) +- Tool: `mcp__plugin_figma_figma__send_code_connect_mappings` +- **Requires: Figma Organization or Enterprise plan** +- Works inside Claude Code via the Figma MCP server +- Fails silently or with a permissions error on Starter/Professional plans + +### CLI Approach (`figma connect publish`) +- Works on **all Figma plan tiers** including free +- Install: `npm install --save-dev @figma/code-connect` +- Define mappings in `.figma.tsx` files alongside your components +- Publish: `npx figma connect publish` + +## CLI Workflow + +```bash +# 1. Install +npm install --save-dev @figma/code-connect + +# 2. Authenticate +npx figma connect auth + +# 3. Create mapping files (one per component) +# NavLink.figma.tsx, BtnPrimary.figma.tsx, etc. + +# 4. Publish to Figma Dev Mode +npx figma connect publish +``` + +## Mapping File Example + +```tsx +// NavLink.figma.tsx +import figma from '@figma/code-connect' +import { NavLink } from './NavLink' + +figma.connect(NavLink, 'https://www.figma.com/design/FILE_KEY/...?node-id=...', { + props: { + label: figma.string('Label'), + href: figma.string('Href'), + }, + example: ({ label, href }) => {label}, +}) +``` + +## When to Use Each + +| Situation | Approach | +|-----------|----------| +| Org/Enterprise plan, want in-context MCP publishing | MCP `send_code_connect_mappings` | +| Starter/Professional plan | CLI only | +| CI/CD automated publishing | CLI (scripted) | +| One-off interactive publish during Claude Code session | Either (if Org plan) | + +## Shumiland Session: 5 Components Published via CLI + +NavLink, BtnPrimary, BtnGradient, BtnDetails, AccordionItem — all published to Dev Mode via CLI without Org plan. diff --git a/wiki/log.md b/wiki/log.md index c46764b..69c319f 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -1,6 +1,17 @@ # Build Log +## [2026-05-10T23:59:00+02:00] compile | daily/2026-05-10.md (addendum — Shumiland workflow concepts) +- Source: daily/2026-05-10.md +- Articles created: + - [[wiki/concepts/eslint-flatcompat-next16-circular-reference]] — FlatCompat wraps eslint-config-next v16 → circular reference crash; drop FlatCompat, import nextConfig directly + - [[wiki/concepts/active-component-import-verification]] — grep import chain before editing; HeaderClient.tsx vs Header.tsx lesson + - [[wiki/concepts/figma-code-connect-plan-requirements]] — MCP `send_code_connect_mappings` requires Org/Enterprise; CLI works on all plans +- Articles updated: none +- Index updates: [[wiki/concepts/_index]] (226→229, +3 entries); [[wiki/_master-index]] (concepts 174→177) +- Note: Three concepts from the Shumiland Code Connect + ESLint + header editing sessions that were missed in prior compilation passes. ESLint FlatCompat is the most actionable — pre-commit hook blocker. Active component import verification is a workflow lesson (editing Header.tsx while app renders HeaderClient.tsx). Code Connect plan requirements clarify when MCP vs CLI is usable. + + ## [2026-05-10T12:00:00+02:00] compile | daily/2026-05-09.md - Source: daily/2026-05-09.md - Articles created (8):