Files
clean-architecture-frontend…/recipes/frontend-capabilities/browser-file-session-capability.ts
T
DongHyeonka d31c7d6b18 fix(recipes): 세션 파일 레시피가 매뉴얼과 같은 capability 타입 위치를 가리킨다
문제: 세션 레시피 주석이 "`FeaturePlatformCapabilities`를
`files: SessionBrowserFiles`로 보강한다"고 적는다. 매뉴얼
(`docs/manual/03-outside-feature-folder.md`)은 그 타입을
`src/features/product-capabilities.ts`의
`ProductFeaturePlatformCapabilities`에 적으라고 하고, `declare module`
보강은 `check:types:node`가 키를 보지 못한다고 막는다. 주석대로 하면 앱
typecheck는 통과하고 node typecheck에서 키를 잃는다. 또 레시피 테스트는
`capabilities: {}`로 조립하고 `files.current()`를 레시피 객체에서 직접
불러서, capability가 기능 쪽으로 넘어가는 절반이 깨져도 통과한다.

고른 방법:
- 주석이 `ProductFeaturePlatformCapabilities`에 적는 예와 매뉴얼 경로를
  보이고, `declare module` 보강은 쓰지 말라고 적는다.
- 레시피 테스트가 `capabilities: { files }`를 돌려주고, 템플릿이 설치된
  기능의 loader에 넘기는 capability 객체(`createInstalledFeatureLoaders`의
  첫 인자)를 기록한다. 테스트의 모든 파일 동작(선택, 읽기, download,
  계정 전환 뒤 새 runtime)을 그 객체의 `files.current()`로 돈다. 같은
  mock 방식은 `tests/recipes/session-owners-runtime.test.ts`가 이미 쓴다.

버린 대안: `files`를 `needs`에 적은 가짜 기능을 생성 index에 끼워 넣기.
`ProductFeaturePlatformCapabilities`가 비어 있는 템플릿에서는 타입을
우회해야 하고, `needs`로 고르는 부분은 1103/09-08 테스트가 이미 잡는다.

위험·한계: 검사는 loader가 받는 capability 객체까지다. 기능 factory가
`needs`로 골라 받는 마지막 단계는 기존 테스트에 맡긴다. 동작 코드는
바뀌지 않는다(주석과 테스트만).

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts
- 변이: 테스트 mock의 `capabilities`에서 `files`를 빼거나,
  `src/bootstrap/runtime-adapters.ts`의 `...product.capabilities`를 지우면
  "Features did not receive the files capability"로 실패해야 한다.

Refs: 1105/02-03
2026-11-05 22:16:46 +09:00

68 lines
2.5 KiB
TypeScript

import type { BrowserFileRuntime } from "../../src/adapters/browser-files/index.ts";
import type { ProductScopeParticipant } from "../../src/bootstrap/product-composition-contract.ts";
/** What features receive: this session's runtime, asked for per operation. */
export type SessionBrowserFiles = Readonly<{
/**
* The current session's runtime, built on first use. Ask again for each
* operation; one kept past a sign-out answers `UNAVAILABLE`.
*/
current(): BrowserFileRuntime;
}>;
/**
* 2026-11-03 02-01. How a product gives features a browser file runtime that
* lives for one session. The runtime does not know the session, and
* `composeProduct` runs once at boot, so the capability is a getter and the
* runtime behind it is disposed by a scope participant on every sign-out and
* account switch: the previous user's selected files, preview object URLs and
* running downloads end there. The next call to `current()` builds a fresh one.
*
* file-transfer is an opt-in recipe (`productionComposition: false`), so the
* template does not build this. A product that installs a feature using it
* types the capability in `src/features/product-capabilities.ts`, as
* `docs/manual/03-outside-feature-folder.md` says:
*
* export interface ProductFeaturePlatformCapabilities {
* readonly files: SessionBrowserFiles;
* }
*
* not with a `declare module` augmentation of `FeaturePlatformCapabilities`,
* whose key `check:types:node` does not see (1105/02-03). The feature lists
* `files` in `needs`, and the product returns both halves from
* `src/bootstrap/product-composition.ts`:
*
* const browserFiles = createSessionBrowserFileCapability(() =>
* createBrowserFileRuntime({ input, policies, limits, download }),
* );
* return {
* capabilities: { files: browserFiles.files },
* credentialProviders: {},
* scopeParticipants: [browserFiles.scopeParticipant],
* };
*
* The runtime options are the product's decisions (policies, limits, the
* download capability resolver); none is chosen here.
*/
export function createSessionBrowserFileCapability(
create: () => BrowserFileRuntime,
): Readonly<{
files: SessionBrowserFiles;
scopeParticipant: ProductScopeParticipant;
}> {
let runtime: BrowserFileRuntime | null = null;
return Object.freeze({
files: Object.freeze({
current: () => (runtime ??= create()),
}),
scopeParticipant: Object.freeze({
label: "browser-files",
close() {
const ending = runtime;
runtime = null;
ending?.dispose();
},
}),
});
}