@zntc/core 0.1.0

package/dist/core/src/config-loader.d.ts

@@ -0,0 +1,157 @@
+/**
+ * zntc.config.{ts,mts,cts,mjs,js,cjs,json} 로더.
+ *
+ * `.ts/.mts/.cts` 는 NAPI `transpile()` 로 self-compile 후 dynamic import.
+ * `.mjs/.js/.cjs` 는 직접 dynamic import. `.json` 은 readFileSync + JSON.parse.
+ *
+ * tmp 파일은 config 옆에 작성해 사용자의 node_modules resolution 을 보존한다
+ * (esbuild `esbuild.config.bundled-*.mjs` 패턴).
+ */
+import type { BuildOptions } from '../index';
+/**
+ * config 객체 형태 — 모든 BuildOptions 의 부분 집합.
+ *
+ * `extends` (`#2108`) 는 다른 config 파일을 base 로 상속받는 식별자 — 단일 string
+ * 또는 배열. config-loader 가 로드 시 자동 해석하므로 최종 사용자 config 에는
+ * 노출되지 않는다 (resolveExtends 가 strip).
+ */
+export type UserConfig = Partial<BuildOptions> & {
+    extends?: string | string[];
+};
+/**
+ * 함수형 config 호출 시 주입되는 컨텍스트 (Vite 호환 형태).
+ *
+ * - `command`: CLI 모드. `bundle` (default), `serve`, `watch`.
+ * - `mode`: `--mode <name>` 으로 지정. 미지정 시 command 별 기본값
+ *   (`serve`/`watch` → `development`, 그 외 → `production`).
+ * - `env`: `process.env` + `.env*` merge 결과. CLI 경로에서는 `loadEnv()` prefix 필터
+ *   결과를 shell env 위에 합쳐 전달한다.
+ */
+export interface ConfigEnv {
+    command: 'bundle' | 'serve' | 'watch';
+    mode: string;
+    env: Record<string, string | undefined>;
+}
+/** 함수형 config — `defineConfig(({ command, mode, env }) => ...)` 형태. */
+export type UserConfigFn = (env: ConfigEnv) => UserConfig | Promise<UserConfig>;
+/** config 파일이 export 가능한 형태 — 객체 또는 함수. */
+export type UserConfigInput = UserConfig | UserConfigFn;
+/**
+ * 자동 탐색 우선순위. 동일 디렉토리에 다중 확장자 존재 시 첫 매치 반환.
+ * 사용자가 의도적으로 여러 형식을 두는 경우는 거의 없으므로 silent precedence 로 충분.
+ *
+ * 같은 배열에서 `TS_EXTS`/`JS_EXTS` 를 derive — 새 확장자 추가 시 한 곳만 고침.
+ */
+export declare const CONFIG_EXT_PRIORITY: readonly [".ts", ".mts", ".cts", ".mjs", ".js", ".cjs", ".json"];
+/**
+ * config 파일을 로드한다. 확장자에 따라 self-compile 또는 직접 import.
+ *
+ * 존재 여부는 사전 stat 으로 확인하지 않고 실제 read/import 의 ENOENT 를 catch
+ * 한다 — TOCTOU 회피 + 1 syscall 절감.
+ *
+ * 함수형 config 가 export 됐으면 `env` 인자를 전달해 호출하고 반환된 객체를 사용한다.
+ * `env` 미제공 시 적절한 기본값 (`command: "bundle", mode: "production"`) 으로 호출.
+ *
+ * @throws 파일이 없거나, 확장자가 지원되지 않거나, 컴파일/평가가 실패하면 throw.
+ */
+export declare function loadConfig(filePath: string, env?: ConfigEnv): Promise<UserConfig>;
+/**
+ * 함수형 config / workspace 가 `env` 인자를 안 받았을 때 사용할 기본 컨텍스트.
+ *
+ * - `command: "bundle"` — production 빌드를 가정 (CLI 주 용도).
+ * - `mode: "production"` — `--mode` 미지정 시의 default.
+ * - `env: process.env` — `import.meta.env.*` 정적 치환에서도 동일 source 사용.
+ *
+ * `loadConfig` 와 `loadWorkspace` 가 공유 — 한 곳에서만 default 정의해 drift 방지.
+ *
+ * @returns 새 `ConfigEnv` 객체 (호출마다 새 참조 — 호출자가 mutate 해도 안전).
+ */
+export declare function defaultConfigEnv(): ConfigEnv;
+/**
+ * `loadModuleDefault` 가 받는 모듈 종류 라벨.
+ *
+ * - 에러 메시지에 라벨로 삽입 (`"config file not found"` vs `"workspace file not found"`).
+ * - tmp 컴파일 파일명에도 사용 (`.zntc-config.bundled-*.mjs` / `.zntc-workspace.bundled-*.mjs`).
+ *
+ * 새 모듈 종류 추가 시 이 union 을 확장하고 호출 사이트도 맞춰 갱신.
+ */
+export type ModuleKind = 'config' | 'workspace';
+/**
+ * 임의 모듈 파일 (TS/JS/JSON) 의 default export 를 로드. `loadConfig` 의 디스패치 로직을
+ * generic 화 — workspace (#2111) 등 config 와 다른 export shape 에서 재사용.
+ *
+ * 분기:
+ *  - `.json`: `readFileSync` + `JSON.parse`
+ *  - `.ts/.mts/.cts`: NAPI `transpile()` self-compile → tmp `.mjs` → dynamic import (cleanup 포함)
+ *  - `.mjs/.js/.cjs`: 직접 dynamic import
+ *
+ * 존재 여부는 사전 stat 으로 확인하지 않고 read/import 의 ENOENT 를 catch — TOCTOU 회피
+ * + 1 syscall 절감.
+ *
+ * @template T 호출자가 기대하는 default export 타입. 런타임 검증은 `allowArray` 외에는 없음.
+ * @param absPath 절대 경로.
+ * @param kind 모듈 종류 — 에러 메시지/임시 파일명에 사용.
+ * @param options `allowArray: true` 면 default export 가 배열일 때도 통과 (workspace 용).
+ * @returns default export (또는 default 가 없으면 namespace 객체).
+ *
+ * @throws `@zntc/core: <kind> file not found: <path>` — 파일 부재
+ * @throws `@zntc/core: failed to parse JSON <kind> ...` — JSON 파싱 실패
+ * @throws `@zntc/core: <kind> compile failed in ...` — TS self-compile 실패 (ZNTC parser 에러)
+ * @throws `@zntc/core: <kind> must export an object or function (got X)` — default 가 잘못된 타입
+ * @throws `@zntc/core: unsupported <kind> extension "<ext>"` — 지원 안 하는 확장자
+ */
+export declare function loadModuleDefault<T>(absPath: string, kind: ModuleKind, options?: {
+    allowArray?: boolean;
+}): Promise<T>;
+/**
+ * 절대 경로를 `file://` URL 로 dynamic import 한 뒤 default export (없으면
+ * namespace 객체) 를 반환한다. 함수형 config 도 허용하므로 객체 또는 함수만 통과.
+ *
+ * `pathToFileURL` 으로 Windows 절대경로 (드라이브 문자) 를 안전하게 처리.
+ * config 로더와 CLI 의 `--plugin <path>` 로더가 공유.
+ *
+ * 같은 프로세스에서 다중 reload 가 필요한 watch (#2107) 는 별도 cache-bust 적용 예정.
+ *
+ * `options.allowArray` 가 `true` 면 array default export 도 통과 — workspace 처럼
+ * top-level array 가 정상인 호출자용. 기본값은 `false` (config/플러그인 호환).
+ */
+export declare function importAndResolveDefault<T = UserConfig>(absPath: string, options?: {
+    allowArray?: boolean;
+}): Promise<T>;
+/**
+ * 파일 부재를 정상 케이스로 처리하는 read. ENOENT/ENOTDIR 면 null, 그 외는 throw.
+ * `.env` 같은 optional 파일 로딩 (`load-env.ts`) 에서 사용.
+ *
+ * ENOTDIR: 부모 경로가 디렉토리가 아닌 케이스 (예: envDir 가 실수로 파일을 가리키는 경우).
+ * optional lookup 의 의미상 "없음"과 동등하므로 swallow.
+ */
+export declare function readFileIfExists(absPath: string): string | null;
+/**
+ * cwd 에서 `zntc.config.*` 자동 탐색. 우선순위는 `CONFIG_EXT_PRIORITY` 참조.
+ *
+ * 동기 stat (`existsSync`) 사용 — CLI 시작 시 한 번만 호출되므로 비용 무시 가능.
+ * parent 디렉토리 traversal 은 모노레포 워크스페이스 (#2111 / Phase 3-4) 에서 처리.
+ *
+ * Note: Zig CLI (`src/main.zig:293` `applyZntcConfigJson`) 은 현재 `.json` 만
+ * 직접 처리한다. 다른 확장자는 JS CLI (`zntc.mjs`) 만 자동 탐색하므로 두 경로의
+ * 동작이 의도적으로 갈린다. 통합은 #2105 (Phase 2-3 bundler 옵션 매핑) 에서.
+ */
+export declare function findConfigPath(cwd: string): string | null;
+/**
+ * mode-specific config 파일 자동 탐색 — `zntc.config.${mode}.{ext}` 형태 (#2110).
+ *
+ * Vite 의 mode 별 config 패턴: base `zntc.config.ts` 가 default, `zntc.config.production.ts`
+ * 같은 mode-specific 파일이 base 를 부분 override. mode 가 비어있거나 매칭 파일 없으면 null.
+ */
+export declare function findModeConfigPath(cwd: string, mode: string): string | null;
+/**
+ * base config + mode-specific config 머지. mode 가 base 를 override.
+ *
+ * 머지 정책 (Vite 호환):
+ *  - scalar / string: mode 값이 정의됐으면 그것 사용
+ *  - 배열: mode 가 정의됐으면 base 를 완전 대체 (concat 안 함 — 의도 명확화)
+ *  - 객체 (`define`/`alias`/`loader`): shallow merge — base 키 + mode 키 (mode 우선)
+ *
+ * `plugins` 는 concat (Vite 와 일치 — 둘 다 적용).
+ */
+export declare function mergeUserConfigs(base: UserConfig, mode: UserConfig): UserConfig;

package/dist/core/src/load-env.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `.env` 파일 로더 (Vite 호환).
+ *
+ * 4단계 우선순위 (낮은 → 높은) 로 머지:
+ *  1. `.env` (general, committed)
+ *  2. `.env.local` (general, gitignored)
+ *  3. `.env.${mode}` (mode-specific, committed)
+ *  4. `.env.${mode}.local` (mode-specific, gitignored)
+ *
+ * `prefixes` 로 시작하는 키만 반환. default 는 `["VITE_", "ZNTC_"]` 두 개:
+ *  - `VITE_` — Vite 호환 prefix (사용자가 Vite 에서 마이그레이션 시 동일 동작)
+ *  - `ZNTC_` — ZNTC 전용 prefix (Vite 와 의도적으로 구분된 키 노출 시)
+ *
+ * 빈 문자열 prefix `""` 를 포함하면 전체 노출 — 주의해서 사용.
+ */
+/**
+ * `mode` 와 `envDir` 기준으로 `.env*` 파일 4종을 우선순위대로 로드 + 머지하고,
+ * `prefixes` 로 시작하는 키만 반환.
+ *
+ * @param mode `--mode <name>` 으로 전달되는 값. 보통 `"production"` / `"development"`.
+ * @param envDir `.env` 파일을 찾을 디렉토리. CLI 의 cwd 기본.
+ * @param prefixes 노출할 키 prefix 목록. default `["VITE_", "ZNTC_"]`. 단일 string 도 허용.
+ */
+export declare function loadEnv(mode: string, envDir: string, prefixes?: string | string[]): Record<string, string>;
+/**
+ * `loadEnv` 결과 + 빌드 컨텍스트를 `import.meta.env.*` define 으로 변환.
+ *
+ * `import.meta.env.MODE` / `PROD` / `DEV` / `SSR` 를 자동 주입한다 (Vite 호환).
+ * 사용자 정의 키는 모두 `JSON.stringify` 로 직렬화해 ZNTC define 에 안전한 리터럴 형태로 전달.
+ */
+export declare function envToDefine(env: Record<string, string>, mode: string, baseUrl?: string): Record<string, string>;

package/dist/core/src/platforms.d.ts

@@ -0,0 +1,35 @@
+/**
+ * NAPI publish 의 platform 매트릭스 단일 source.
+ *
+ * 새 platform 추가 시 (예: musl, riscv, android):
+ *   1. 여기에 entry 추가
+ *   2. `packages/core-{name}/` skeleton 생성 (package.json + README)
+ *   3. `packages/core/index.ts:getPlatformPackage()` 매핑 추가
+ *   4. `.github/workflows/release.yml` 매트릭스에 추가 (이 파일과 sync — YAML 정적 한계)
+ *   5. `.github/workflows/ci.yml:napi-package-smoke` 매트릭스도 sync
+ *
+ * win32 정책: napi-rs/swc/oxc 컨벤션 따름 — MSVC 만 publish, mingw/gnu 안 함
+ * (GHA windows-latest = MSVC node 라 install 매칭 자체가 의미 없음).
+ */
+export interface PlatformTarget {
+    /** sub-package suffix (e.g. "linux-x64-gnu"). `@zntc/core-${name}` 가 npm 이름. */
+    name: string;
+    /** npm `os` 필드 — install 매칭. */
+    npmOs: 'linux' | 'darwin' | 'win32';
+    /** npm `cpu` 필드. */
+    npmCpu: 'x64' | 'arm64' | 'ia32';
+    /** npm `libc` 필드 (linux 만). */
+    npmLibc?: 'glibc' | 'musl';
+    /** `zig build napi -Dtarget=<zigTarget>` */
+    zigTarget: string;
+    /** GitHub Actions runner — release.yml/ci.yml 매트릭스에서도 동일 사용. */
+    ghaRunner: string;
+}
+export declare const PLATFORMS: PlatformTarget[];
+export declare function subPackageName(platform: PlatformTarget): string;
+export declare function subPackageDir(platform: PlatformTarget): string;
+/**
+ * findAddon() 의 "Supported: ..." 에러 메시지용 — PLATFORMS 변경 시 자동 반영.
+ * 동일 (os, cpu) 에 glibc/musl 둘 다 있으면 "(glibc/musl)" 로 합쳐 표기.
+ */
+export declare function formatSupportedPlatforms(): string;

package/dist/core/src/runtime-polyfills.d.ts

@@ -0,0 +1,94 @@
+import { createRequire } from 'node:module';
+export type RuntimePolyfillMode = 'auto' | 'usage' | 'entry';
+export type RuntimePolyfillProvider = 'core-js';
+export interface RuntimePolyfillOptions {
+    /**
+     * Runtime polyfill injection strategy.
+     *
+     * `auto` and `usage` select from graph-detected API usage, while `entry`
+     * injects all target-required core-js ES/Web modules.
+     */
+    mode?: RuntimePolyfillMode;
+    /** Polyfill provider. Only `core-js` is currently supported. */
+    provider?: RuntimePolyfillProvider;
+    /**
+     * Browserslist targets for core-js-compat, matching Rspack/SWC `env.targets`.
+     *
+     * Examples: `["chrome >= 87", "edge >= 88", "firefox >= 78", "safari >= 14"]`.
+     * Physical device names such as `"iPhone 8"` and compact shorthands such as
+     * `"ios12"` are rejected.
+     */
+    targets?: string | string[];
+    /** core-js version used for compatibility calculation, matching Rspack/SWC `env.coreJs`. */
+    coreJs?: string;
+    /** Additional core-js modules to force into the runtime prelude. */
+    include?: string[];
+    /** core-js modules to remove after target and usage calculation. */
+    exclude?: string[];
+    /** Include proposal polyfills when querying core-js-compat. */
+    proposals?: boolean;
+}
+export type RuntimePolyfillsOption = 'off' | RuntimePolyfillMode | RuntimePolyfillOptions;
+export interface RuntimePolyfillBuildOptions {
+    entryPoints: string[];
+    platform?: string;
+    target?: string;
+    browserslist?: string | string[];
+    runtimePolyfills?: RuntimePolyfillsOption;
+    coreJs?: string;
+    runBeforeMain?: string[];
+    resolveExtensions?: string[];
+}
+interface NormalizedRuntimePolyfills {
+    mode: RuntimePolyfillMode;
+    provider: RuntimePolyfillProvider;
+    targets: CoreJsTargets;
+    include: string[];
+    exclude: string[];
+    proposals: boolean;
+    coreJsVersion?: string;
+}
+type CoreJsTargetObject = Record<string, string | number>;
+type CoreJsTargets = string | string[] | CoreJsTargetObject;
+type RuntimeRequire = ReturnType<typeof createRequire>;
+type RuntimePolyfillFeature = string;
+export interface ResolvedRuntimeModule {
+    module: string;
+    path: string;
+}
+export interface ResolvedRuntimeCandidate extends ResolvedRuntimeModule {
+    feature: RuntimePolyfillFeature;
+}
+/** NAPI 로 전달되는 단일 plan 객체. usage 모드는 candidates, entry 모드는 entry 를 채운다. */
+export interface RuntimePolyfillNativePlan {
+    mode: 'usage' | 'entry';
+    candidates?: readonly ResolvedRuntimeCandidate[];
+    entry?: readonly ResolvedRuntimeModule[];
+    include?: readonly ResolvedRuntimeModule[];
+    exclude?: readonly string[];
+}
+/** @internal */
+export declare const __runtimePolyfillTestHooks: {
+    reset(): void;
+    setRuntimeRequire(runtimeRequire: RuntimeRequire | null): void;
+};
+/** @internal — Zig 매핑 테이블과의 sync 검증용. 외부 사용자는 사용 금지. */
+export declare const __runtimePolyfillTestInternals: {
+    readonly featureModules: Readonly<typeof RUNTIME_POLYFILL_FEATURE_MODULES>;
+};
+declare const RUNTIME_POLYFILL_FEATURE_MODULES: readonly {
+    feature: RuntimePolyfillFeature;
+    module: string;
+}[];
+export declare function isEsTarget(target: string | undefined): boolean;
+export declare function normalizeRuntimeTargets(targets: string | string[]): string | string[];
+export declare function normalizeRuntimePolyfillOptions(options: RuntimePolyfillBuildOptions): NormalizedRuntimePolyfills | null;
+export declare function computeCoreJsCompatModules(targets: CoreJsTargets, modules: string[] | RegExp, options?: {
+    version?: string;
+    proposals?: boolean;
+}): string[];
+export declare function applyRuntimePolyfillsToNapiOptions(napiOptions: Record<string, unknown>, options: RuntimePolyfillBuildOptions): {
+    cleanup: () => void;
+    modules: string[];
+};
+export {};

package/dist/core/src/schema-allowlists.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Schema sync 테스트 공통 allowlist — `BuildOptionsCommon` 에 정의되어 있지만 사용자가 직접
+ * 명시할 일 없는 **NAPI/internal/번들러-전용** 옵션 집합.
+ *
+ * 사용처:
+ *  - `packages/core/src/typo-suggest.test.ts`: `KNOWN_CONFIG_KEYS` 미포함 정당화 (사용자가
+ *    `zntc.config.*` 에 적을 일 없으므로 typo 검출 대상 아님)
+ *  - `packages/core/bin/zntc-cli-schema-sync.test.ts`: CLI flag 미노출 정당화
+ *
+ * Zig DTO sync (`src/transpile_options_dto_test.zig:ts_buildoptions_only_allowlist`) 는 별
+ * 언어라 별도 유지 — 새 internal 키 추가 시 양쪽 모두 갱신 필요. (TypeScript Compiler API
+ * 도입 + codegen 으로 single source 화는 ROI 낮아 보류, future work.)
+ *
+ * 새 internal 키 추가 시 여기 1곳에만 등록 → 두 TS 테스트 모두 자동 통과. 각 테스트의 추가
+ * allowlist (테스트만의 특수 케이스) 는 그대로 유지.
+ */
+export declare const NAPI_INTERNAL_ONLY_KEYS: readonly ["allowOverwrite", "assetRegistry", "blockList", "collectModuleCodes", "configurableExports", "devMode", "emitDiskSourcemap", "entryErrorGuard", "experimentalCodeCache", "fallback", "globalIdentifiers", "onReady", "onRebuild", "polyfills", "reactRefresh", "rootDir", "runBeforeMain", "scopeHoist", "silentConsoleErrorPatterns", "strictExecutionOrder", "watchExclude", "watchFolders", "watchInclude", "workletPluginVersion", "workletTransform", "write"];

package/dist/core/src/typo-suggest.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Typo 검출 및 "did you mean ...?" 제안 (#2109).
+ *
+ * `levenshtein` 으로 알려진 옵션 키와 비교해 거리 ≤ threshold 인 가장 가까운
+ * 키를 제안. config 파일의 unknown 키, CLI flag 의 unknown name 둘 다 사용.
+ */
+/**
+ * `unknown` 과 가장 가까운 `known` 키 중 거리 `<= threshold` 인 것 반환.
+ *
+ * threshold 기본 2 — 짧은 키 (3자 이하) 는 거리 2 만 허용해도 false positive 가
+ * 많아질 수 있으므로 길이별로 자동 조정 (`Math.min(threshold, ceil(len/3))`).
+ *
+ * 다중 매치 시 가장 짧은 거리, 동률이면 알파벳순.
+ */
+export declare function suggestKey(unknown: string, known: readonly string[], threshold?: number): string | null;
+/**
+ * config 객체의 모든 키를 검사해 unknown 발견 시 console.warn 으로 경고 + 제안.
+ *
+ * `silent: true` 면 출력 안 하고 `{ unknown, suggestion }` 배열만 반환 — 테스트용.
+ */
+export declare function warnUnknownKeys(config: Record<string, unknown>, known: readonly string[], options?: {
+    silent?: boolean;
+    sourceLabel?: string;
+}): Array<{
+    unknown: string;
+    suggestion: string | null;
+}>;
+/**
+ * 알려진 BuildOptions / TranspileOptions / config-only 키 (`extends` 등) 통합 목록.
+ *
+ * TypeScript 타입은 런타임에 지워지므로 `warnUnknownKeys()` 가 이 목록을 직접
+ * `BuildOptions` 에서 읽을 수는 없다. 그래서 런타임 값은 수동 목록으로 유지한다.
+ *
+ * drift 는 `typo-suggest.test.ts` 가 `BuildOptionsCommon` 선언을 파싱해 CI 에서
+ * 검출한다. 완전한 단일 source of truth 화는 #2112 (Phase 3-5 schema sync) 에서
+ * `BuildOptions` / Zig DTO / config key 목록을 빌드타임 생성 대상으로 묶을 때 가능하다.
+ */
+export declare const KNOWN_CONFIG_KEYS: readonly string[];

package/dist/core/src/workspace.d.ts

@@ -0,0 +1,185 @@
+/**
+ * `zntc.workspace.{ts,mts,cts,mjs,js,cjs,json}` 모노레포 워크스페이스 로더 (#2111).
+ *
+ * Vitest `vitest.workspace.ts` 패턴 벤치마킹. root 디렉토리에 단일 워크스페이스
+ * 파일을 두고, 그 안에서 패키지별 build target 을 정의한다.
+ *
+ * ```ts
+ * export default defineWorkspace([
+ *   "./packages/app",          // 디렉토리 — 안의 zntc.config.* 자동 탐색
+ *   "./packages/*",             // glob — 매칭 디렉토리들 일괄
+ *   { name: "shared", entryPoints: [...] },  // inline — 즉시 워크스페이스화
+ * ])
+ * ```
+ *
+ * `--workspace=<name>` 으로 단일 entry 만 빌드 가능. root config (`zntc.config.*`)
+ * 와 같은 디렉토리에 두면 root 옵션을 모든 entry 가 상속.
+ */
+import { type ConfigEnv, type UserConfig } from './config-loader.ts';
+declare const CONFIG_EXT_PRIORITY_LOCAL: readonly [".ts", ".mts", ".cts", ".mjs", ".js", ".cjs", ".json"];
+/**
+ * 디렉토리 경로 또는 단일 `*` 가 포함된 glob.
+ *
+ * - `"./packages/app"` — 단일 디렉토리. 안의 `zntc.config.*` 가 있으면 자동 로드.
+ * - `"./packages/*"` — trailing wildcard. baseDir 의 직속 디렉토리 모두 매칭 (hidden / `node_modules` 제외).
+ * - `"./apps/web-*"` — prefix 매칭도 동일 규칙.
+ *
+ * `**` (재귀 glob) 은 미지원 — 워크스페이스에서 흔치 않고 perf/edge case 가 늘어 의도적 제외.
+ */
+export type WorkspaceEntryPath = string;
+/**
+ * 디렉토리 없이 root cwd 에서 직접 build 되는 inline entry.
+ *
+ * `name` 은 식별자(필수) — `--workspace=<name>` 필터, 로그 출력에 사용. 그 외 모든 필드는
+ * `BuildOptions` (`UserConfig`) 와 동일하며 root config 를 override 한다.
+ *
+ * @example
+ * ```ts
+ * export default defineWorkspace([
+ *   { name: "shared-utils", entryPoints: ["./shared/utils.ts"], outdir: "./shared/dist" },
+ * ]);
+ * ```
+ */
+export type WorkspaceEntryInline = UserConfig & {
+    name: string;
+};
+/** workspace 배열 원소 — string path/glob 또는 inline 객체. */
+export type WorkspaceEntry = WorkspaceEntryPath | WorkspaceEntryInline;
+/** workspace 파일이 export 하는 entries 배열. */
+export type Workspace = WorkspaceEntry[];
+/**
+ * 함수형 workspace — `defineWorkspace((env) => [...])`.
+ *
+ * `env.command` (`bundle`/`serve`/`watch`), `env.mode`, `env.env` (process.env 기반)
+ * 를 받아 동적으로 entries 결정. 비동기 (Promise) 반환 허용.
+ */
+export type WorkspaceFn = (env: ConfigEnv) => Workspace | Promise<Workspace>;
+/** workspace 파일이 default export 가능한 형태 — 배열 또는 함수. */
+export type WorkspaceInput = Workspace | WorkspaceFn;
+/**
+ * Vitest 식 identity 헬퍼. 입력을 그대로 반환 — 타입 추론 / IDE 자동완성을 위해 존재.
+ *
+ * @param input workspace 정의 — 배열 또는 함수형
+ * @returns 입력 그대로 (런타임 변경 없음)
+ *
+ * @example
+ * ```ts
+ * import { defineWorkspace } from "@zntc/core";
+ *
+ * export default defineWorkspace([
+ *   "./packages/*",
+ *   { name: "shared", entryPoints: ["./shared/index.ts"] },
+ * ]);
+ * ```
+ */
+export declare function defineWorkspace<T extends WorkspaceInput>(input: T): T;
+/**
+ * workspace 파일 자동 탐색 우선순위. `CONFIG_EXT_PRIORITY` 와 동일 정책 — 동일 디렉토리에
+ * 다중 확장자 존재 시 첫 매치를 반환한다 (`.ts` > `.mts` > `.cts` > `.mjs` > `.js` > `.cjs` > `.json`).
+ */
+export declare const WORKSPACE_EXT_PRIORITY: typeof CONFIG_EXT_PRIORITY_LOCAL;
+/**
+ * `cwd` 에서 `zntc.workspace.{ext}` 를 자동 탐색.
+ *
+ * @param cwd 탐색 시작 디렉토리 (보통 `process.cwd()`)
+ * @returns 발견된 절대 경로 또는 `null`
+ *
+ * 동기 stat (`existsSync`) 사용 — CLI 시작 시 한 번만 호출되므로 무시 가능한 비용.
+ * parent traversal 은 안 함 — 모노레포 root 가 아닌 sub-package 안에서 호출되면 `null` 반환.
+ */
+export declare function findWorkspacePath(cwd: string): string | null;
+/**
+ * workspace 파일 로드. `loadModuleDefault` 가 TS/JS/JSON 디스패치 + (tmp 파일) self-compile
+ * 까지 처리하므로 호출자는 단일 진입점만 알면 된다. 함수형 export 면 `env` (또는
+ * `defaultConfigEnv()`) 와 호출. 결과는 항상 검증된 entries 배열.
+ *
+ * @param filePath workspace 파일 — 절대 또는 cwd 기준 상대 경로
+ * @param env 함수형 workspace 호출 시 주입할 컨텍스트. 미제공 시 `defaultConfigEnv()`.
+ * @returns 검증된 entries 배열 (순서 유지)
+ *
+ * @throws `@zntc/core: workspace must export an array (got X) from <path>` — top-level 배열 아님
+ * @throws `@zntc/core: workspace[i] is empty string in <path>` — 빈 문자열 entry
+ * @throws `@zntc/core: workspace[i] must be a string or object (got X) in <path>` — 잘못된 타입
+ * @throws `@zntc/core: workspace[i] inline entry requires non-empty 'name' in <path>` — inline 인데 name 없음
+ *
+ * @example
+ * ```ts
+ * const ws = await loadWorkspace("zntc.workspace.ts", { command: "bundle", mode: "production", env: process.env });
+ * // ws: WorkspaceEntry[]
+ * ```
+ */
+export declare function loadWorkspace(filePath: string, env?: ConfigEnv): Promise<Workspace>;
+/**
+ * 식별 단계 결과 — cwd/name/source 만 확정하고 config 로드는 보류.
+ *
+ * `loadIdentifiedConfig` 로 후처리하면 `config: UserConfig` 가 채워진 build target 형태로 완성.
+ */
+export interface IdentifiedWorkspace {
+    /** 워크스페이스 식별자 — `--workspace=<name>` 필터 키. */
+    name: string;
+    /** 매칭/지정된 cwd 절대 경로. */
+    cwd: string;
+    /** 어떤 entry 형식에서 왔는지. */
+    source: 'path' | 'glob' | 'inline';
+    /** inline 인 경우 미리 알려진 config (name 필드는 제외). path/glob 는 `null` — 디스크에서 로드 필요. */
+    inlineConfig: UserConfig | null;
+}
+/**
+ * entries 를 식별 단계까지만 처리 — `cwd`/`name`/`source` 결정하고 config 로드는 보류.
+ *
+ * `--workspace=<name>` 필터를 config 로드 **전에** 적용해 비용 큰 TS config self-compile 을
+ * 필터링된 N-1 개 entry 에 대해 회피하기 위함. path entry 는 `package.json` 만 읽어 name
+ * 결정 (저렴), glob 은 디렉토리 enumerate.
+ *
+ * dedup: 같은 `cwd` 가 path + glob 양쪽에 매칭되면 **첫 번째 (선언 순서)** 만 유지. 명시적
+ * path 가 glob 보다 우선하는 자연스러운 의도 — 사용자가 "all packages 중 app 은 특별 설정"
+ * 같은 패턴을 쓸 수 있게.
+ *
+ * @param entries `loadWorkspace` 가 반환한 검증된 entries 배열
+ * @param rootDir workspace 파일이 있는 디렉토리 (절대 경로 권장)
+ * @returns 식별된 워크스페이스 목록 (선언 순서 유지, dedup 적용)
+ *
+ * @throws `@zntc/core: workspace glob '**' is not supported (got '<pattern>')` — `**` glob 사용
+ * @throws `@zntc/core: workspace glob with '*' in directory part is not supported (got '<pattern>')` — 디렉토리부 wildcard
+ *
+ * @example
+ * ```ts
+ * const ws = await loadWorkspace("zntc.workspace.ts");
+ * const ids = identifyWorkspaceEntries(ws, "/repo");
+ * const target = filterWorkspaces(ids, "my-app");
+ * const resolved = await Promise.all(target.map((w) => loadIdentifiedConfig(w)));
+ * ```
+ */
+export declare function identifyWorkspaceEntries(entries: Workspace, rootDir: string): IdentifiedWorkspace[];
+/**
+ * 식별된 entry 의 config 를 디스크에서 로드. path/glob 은 `findConfigPath` 로 cwd 안의
+ * `zntc.config.*` 자동 탐색 후 `loadConfig` (extends 처리, 함수형 호출 포함). inline 은
+ * 이미 갖고 있는 `inlineConfig` 그대로.
+ *
+ * 비싸다 — TS config 면 NAPI transpile + tmp `.mjs` write/import/unlink. 필터링된 entry
+ * 에 대해서만 호출하는 것을 권장 (`identifyWorkspaceEntries` → `filterWorkspaces` → 이 함수).
+ *
+ * @param w 식별된 워크스페이스 entry
+ * @param env `loadConfig` 에 전달할 함수형 config 컨텍스트
+ * @returns entry 의 config (inline 또는 디스크 로드 결과). config 파일 없으면 빈 객체 `{}`.
+ */
+export declare function loadIdentifiedConfig(w: IdentifiedWorkspace, env?: ConfigEnv): Promise<UserConfig>;
+/**
+ * `--workspace=<name>` 필터. 매칭 0개면 throw — 사용자 typo 보호 (가능한 후보 노출).
+ *
+ * `name` 필드를 가진 객체면 모두 받도록 generic — `IdentifiedWorkspace` 든 caller 가 정의한
+ * 후속 형태든 동일 동작. config 로드는 비싸므로 `identifyWorkspaceEntries` 결과에 즉시 필터
+ * 후 `loadIdentifiedConfig` 호출을 권장.
+ *
+ * `name` 일치만 사용 — Vitest 의 `--project` 와 동일. glob/regex 매칭은 향후 확장.
+ *
+ * @param workspaces 식별/해석된 워크스페이스 배열
+ * @param filter `--workspace=<name>` 값. `undefined`/빈 문자열이면 전체 그대로 반환.
+ * @returns `name === filter` 인 entries (보통 1개). filter 미지정 시 입력 동일 참조 반환.
+ *
+ * @throws `@zntc/core: --workspace='<filter>' matched 0 entries (available: ...)` — 매칭 실패
+ */
+export declare function filterWorkspaces<T extends {
+    name: string;
+}>(workspaces: T[], filter: string | undefined): T[];
+export {};