DongHyeonkaandClaude Opus 5 82e992d066 fix: Studio 리뷰 지적을 반영하고 죽은 머리말 컴포넌트를 걷어낸다
에디터 칸 이름을 공개 화면과 맞춘다. 목적→이 기준을 쓰는 이유, 규칙→판단
기준, 적용 조건→적용할 때, 예외→예외와 주의, 사실→확인한 사실,
미지수→남은 미지수, 선택지→검토한 선택지. 쓰는 사람이 지금 채우는 칸이
공개 화면 어디로 가는지 외우지 않아도 된다.

대시보드의 세 칸이 같은 목록을 세 번 반복했다. 「검증과 미리보기」와
「게시 준비」가 「이어서 작성」을 걸러 낸 부분집합인데 「이어서 작성」은
전체를 그대로 그렸기 때문이다 — 모든 문서가 같은 단계면 세 칸이 겹친다.
각 문서는 지금 서 있는 구간 한 곳에만 나온다.

릴리스에서 「상태 공개 · 공개일 2026-08-22」 옆에 「아직 공개하지 않음」이
같이 나왔다. 경로가 비었다고 미공개는 아니다 — 공개 여부는 상태가 말한다.

행에서 눈에 띄는 단 하나가 되돌릴 수 없는 동작이었다. 편집을 같은 격의
버튼으로 올리고, 삭제는 danger 로 낮추고, 격자에 자리를 만들어 다음 줄로
떨어지지 않게 한다. 게시 기록이 이미 그 모양이었다.

주제·프로젝트는 「다음: 내용 편집」을 안내하면서 그 줄의 버튼은 게시 취소와
삭제뿐이었다. 공개 프로젝트 화면이 비어 있던 이유가 여기다.

죽은 코드였던 PublicDocumentHeader 를 걷어낸다. 화면을 실제로 그리는 것은
PublicRecordRenderer 이고 그 컴포넌트는 아무도 부르지 않았다 — 어제 이
컴포넌트에 줄바꿈을 고쳐 넣었지만 화면에는 닿지 않았다. 그 자리를 지키던
가드도 진짜로 그려지는 쪽으로 옮긴다.

탭 제목과 설명에 문서를 반영한다. 공개 문서가 전부 "Reference · Tech Log"
였고 설명은 모든 화면이 "Tech Log frontend" 하나였다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-08-31 09:01:03 +09:00

Tech Log Frontend

Initialized from clean-architecture-frontend-template revision 4dc033cf33a5b6173bbf960d5eb464a406dc4c92. The exact source identity is recorded in template.lock.json.

A React/Vite TechLog application where architecture boundaries, integration behavior, release coherence, accessibility, performance, and operations are executable contracts rather than conventions.

Start locally

Requirements: the exact Node.js version in .nvmrc (currently 24.14.0) and Corepack. The repository pins pnpm in package.json.

Product source, tests, build/quality scripts, and supported tool configuration are TypeScript/TSX. allowJs is disabled. Node-side .ts scripts run directly on the pinned Node 24 runtime and are checked with NodeNext resolution plus erasable-syntax enforcement. Project-owned executable source contains no JavaScript-family files; negative architecture, security, and type-compatibility fixtures are TypeScript/TSX as well.

corepack pnpm install --frozen-lockfile
corepack pnpm dev

Runtime-public settings live in public/config.json and are validated before the product tree mounts. Client secrets are forbidden.

TechLog experience

The default build mounts the source-faithful TechLog Public and Studio experience. Public routes provide discovery, search, documents, topics, projects, releases, and profile content. /studio provides the session-scoped mock authoring workflow: create, edit, validate, preview, publish, unpublish, and immutable publication history.

The 27 canonical route definitions are divided into PUBLIC and STUDIO nested layouts. Studio authentication remains deliberately deferred; its mock gateway state lasts for one Studio shell session and resets on a full document load. The exact route, dependency, stylesheet, asset, and parity inventory is recorded in docs/operations/techlog-ui-migration-baseline.md.

corepack pnpm build emits a self-contained dist/server.mjs production boundary. corepack pnpm preview --host 127.0.0.1 --port 4174 serves known Public and Studio routes as SPA documents, preserves the in-shell Studio 404, and returns source-exact raw 404 text/plain responses for missing Public content. With the read-only source temp-copy server on 4375, run:

TECH_LOG_SOURCE_URL=http://127.0.0.1:4375 \
TECH_LOG_TARGET_URL=http://127.0.0.1:4174 \
corepack pnpm verify:tech-log-source-parity

Studio backend source

TECH_LOG_STUDIO_SOURCE (MOCK | HTTP) selects which StudioGateway adapter the composition root wires up. It defaults to MOCK — the session-scoped in-memory Studio described above — so the existing Studio workflow and its test suites are unaffected unless the switch is deliberately turned on. Setting it to HTTP wires the HTTP StudioGateway instead, which calls the canonical @tech-log/studio-contract operations against API_BASE_URL. With no backend reachable at that URL, Studio still boots and its shell renders; the specific panels that need the backend show an inline "failed to load" state rather than a blank screen or an unhandled exception.

The switch is a field on the versioned runtime config document (RuntimeConfigV2), not a build-time flag:

  • config/runtime/{local,development,staging,production}.json are the deployment profiles corepack pnpm build (via scripts/generate-runtime-config.ts) materializes into dist/config.json for a real build.
  • corepack pnpm dev does not run that step. Plain vite serves public/config.json (and public/release-manifest.json) verbatim as dev fixtures — editing config/runtime/local.json alone has no effect on pnpm dev. To exercise HTTP mode under pnpm dev, set TECH_LOG_STUDIO_SOURCE in public/config.json directly.

The dev release manifest must declare the compiled contract set

Contract-set verification runs unconditionally at boot, before any adapter is selected. It is not an HTTP-mode caveat: if public/release-manifest.json's contractSet does not match the set the build compiled, corepack pnpm dev does not start the app at all — it renders the fail-closed boot screen (CONTRACT_SET_MISMATCH / CONTRACT_SET_PACKAGE_MISSING) in the default MOCK mode too. A developer who runs pnpm dev and gets a boot error has a broken dev server, however tidy the screen looks; treat it as a defect in the fixture, never as expected behaviour.

The expectation comes from EXPECTED_CONTRACT_SET_PACKAGES (src/features/installed-contract-contributions.ts), and a real build writes it into dist/release-manifest.json from scripts/generate-contract-set.ts, so production builds are always self-consistent. Only the hand-maintained dev fixture can drift, and it drifts whenever either half moves — a regenerated contract (new package digest or version) or a contribution added to or removed from installed-contract-contributions.ts. Two things keep it honest:

  • corepack pnpm generate:tech-log-contract refreshes the fixture's contractSet block as its last step, so regenerating the contract can never leave the two out of step. corepack pnpm generate:dev-release-manifest refreshes the same block on its own, for the contribution-list case that does not go through contract generation.
  • corepack pnpm check:dev-release-manifest is the gate. It compares the fixture's setAlgorithm, setDigest and package set against the compiled set and fails on any difference. It runs in CI as part of FE-GATE-010, which is what catches the changes the generation step cannot see.

TechLog contract generation

The Studio HTTP contract is vendored from a canonical OpenAPI source, not hand-written:

  • corepack pnpm generate:tech-log-contract regenerates src/features/tech-log/contracts/studio/studio-api.openapi.yaml, generated.ts, and canonical-source.json from the canonical tech-log-design-package repository (path from TECH_LOG_DESIGN_PACKAGE, default /home/donghyeon/workspace/tech-log-design-package). It needs that repository checked out locally and network access, because type generation runs in an isolated pnpm dlx sandbox (this repo pins TypeScript 7, which has no classic compiler API for openapi-typescript to use). Run it after the canonical contract changes, then commit the regenerated files.
  • corepack pnpm check:tech-log-contract is the drift gate: it hashes the vendored yaml against the recorded digest and confirms every recorded operationId is present in both the yaml and the generated types. It needs neither the canonical repository nor the network, so it runs in CI and in this sandbox. Run it any time to confirm the vendored contract has not drifted from what was last generated.

Architecture

Dependencies point inward:

presentation -> application -> domain
adapters -----^
bootstrap composes concrete adapters
contracts own cross-cutting registries

See docs/architecture/overview.md, docs/architecture/layers.md, and docs/architecture/starter-experience.md. TechLog is one feature boundary under src/features/tech-log. Its immutable Public catalog and session-scoped Studio mock gateway are injected through the application feature input; Public and Studio presentation code shares the typed content renderer without importing concrete adapters. The retained reference feature remains a non-product platform contract fixture and can be removed without changing the TechLog route set.

Platform capability review

The starter shell is implemented, but the repository review also records the remaining work required before feature teams can use every declared contract through one end-to-end application path:

These documents distinguish repository defaults from opt-in adapters and project-owned integrations. They are target designs and review findings; a capability is not treated as implemented until its branch acceptance criteria and executable gates pass.

Verification

Common local checks:

corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:types:app
corepack pnpm check:types:node
corepack pnpm check:types:test
corepack pnpm check:architecture
corepack pnpm test:all
corepack pnpm test:e2e
corepack pnpm test:a11y
corepack pnpm build
corepack pnpm check:bundle
corepack pnpm test:performance
corepack pnpm verify:compatibility
corepack pnpm verify:release
corepack pnpm check:registries
corepack pnpm drill:runbooks
corepack pnpm check:ci
corepack pnpm exec vitest run tests/features/tech-log
corepack pnpm exec playwright test tests/e2e/tech-log-public-discovery.spec.ts tests/e2e/tech-log-studio-workflow.spec.ts tests/e2e/tech-log-responsive.spec.ts tests/e2e/tech-log-accessibility.spec.ts --project=chromium
corepack pnpm test:visual

check:types는 source, Node scripts/config와 tests를 분리된 TypeScript project로 모두 검사한다. type/architecture/security/registry의 invalid fixture는 config/ci/gates.json에서 “실패해야 통과”하는 negative gate로 실행된다. 도구 호환성 결정은 VD-01에 기록돼 있다.

Application feature input은 module augmentation으로 닫힌 ID와 정확한 input shape를 제공하며, 공통 Result<Value, Failure = AppFailure>는 error registry의 failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는 TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고 runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import, parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용 TypeScript/TSX negative fixture로도 검증된다.

Install the pinned Playwright browser engines before the first cross-browser run:

corepack pnpm exec playwright install --with-deps chromium firefox webkit

Two gates intentionally need external evidence:

  • review:a11y-manual needs a signed human keyboard/focus/screen-reader review for all 27 registered routes: NOT_FOUND, TECH_LOG_CASE, TECH_LOG_EXPLORE, TECH_LOG_EXPLORE_KIND, TECH_LOG_HOME, TECH_LOG_PROFILE, TECH_LOG_PROJECT, TECH_LOG_PROJECTS, TECH_LOG_PROJECT_ACTIVITY, TECH_LOG_PROJECT_DECISIONS, TECH_LOG_PROJECT_RECORDS, TECH_LOG_QUESTION, TECH_LOG_REFERENCE, TECH_LOG_RELEASE, TECH_LOG_RELEASES, TECH_LOG_SEARCH, TECH_LOG_STUDIO_DOCUMENTS, TECH_LOG_STUDIO_DOCUMENT_EDIT, TECH_LOG_STUDIO_DOCUMENT_NEW, TECH_LOG_STUDIO_DOCUMENT_PREVIEW, TECH_LOG_STUDIO_DOCUMENT_PUBLISH, TECH_LOG_STUDIO_DOCUMENT_VALIDATION, TECH_LOG_STUDIO_HOME, TECH_LOG_STUDIO_NOT_FOUND, TECH_LOG_STUDIO_PUBLICATIONS, TECH_LOG_STUDIO_PUBLICATION_PREVIEW, TECH_LOG_TOPIC. verify:documentation derives that list from the route registry and fails if this paragraph falls behind it.
  • collect:web-vitals-evidence stays FAIL_UNVERIFIED until a reviewed minimum eligible-sample threshold and 28 days of production data exist.

Live release verification additionally requires HOSTING_BASE_URL.

CI and evidence

The 26-gate registry is config/ci/gates.json; the Gitea workflow is .gitea/workflows/quality-gates.yml. It follows:

MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY

DOCUMENTATION_READY is independent. No gate is downgraded to a warning. Machine-readable evidence is written below artifacts/; generated evidence is ignored by Git while .gitkeep files preserve the taxonomy.

Operational details are in docs/operations/, with incident procedures in docs/runbooks/.

S
Description
No description provided
Readme
47 MiB
Languages
TypeScript 96.9%
CSS 3%