프로젝트에 Zuke 설정하기
Zuke는 Deno에서 실행되는 TypeScript 클래스로 빌드를 정의합니다. 각 타겟은
클래스 필드이며, 타겟은 문자열이 아닌 this.<필드>로 서로를 참조합니다.
패키지는 npm이 아닌 JSR(jsr:@zuke/...)에서 가져옵니다.
빠른 경로: zuke setup
@zuke/cli 도구가 모든 것을 스캐폴딩합니다. 한 번 설치한 후 대상 프로젝트에서 setup을 실행하세요:
deno install -A -g -n zuke jsr:@zuke/cli # 한 번, 전역 설치
zuke setup # 프로젝트 루트에서 실행
./zuke # 빌드 실행
전역 설치가 없나요? 동일한 마법사가 직접 실행됩니다:
deno run -A jsr:@zuke/cli setup
setup 플래그: --dir <경로>, --name <클래스명>, --force (기존 파일 덮어쓰기),
--yes (비대화형), --launcher-name <이름> (이미 zuke/ 디렉토리가 존재할 때
런처를 다른 이름으로 작성 — 디렉토리 충돌 시 이제 자동으로 건너뛰는 대신
실행 가능한 오류 메시지를 출력합니다).
Node 저장소의 @types/node 잡음 없이 @zuke/* 패키지의 API를 읽으려면
zuke doc <패키지>(예: zuke doc core)를 실행하세요 — 격리된 디렉토리에서
deno doc을 실행합니다.
기존 프로젝트 마이그레이션: zuke import
프로젝트에 이미 package.json 스크립트나 Makefile이 있다면 setup보다
zuke import를 선호하세요 — 이를 읽어 빈 빌드 대신 작업당 타겟이 있는
zuke.ts를 생성합니다:
zuke import # package.json을 자동 감지한 후 Makefile 감지
zuke import --from makefile # 소스 고정 (package.json | makefile)
각 스크립트/타겟은 target()이 됩니다. 명령어는 CmdTasks.exec(...)에 매핑됩니다 —
플레이스홀더이며 최종 목적지가 아닙니다: 이를 수용하기 전에 패키지 카탈로그
(llms.txt의 ## Packages 목록 또는
zuke-write-build 요약표의 표)에서
해당 명령어와 일치하는 @zuke/<도구> 래퍼가 있는지 확인하고 플레이스홀더를
그것으로 대체하세요 — 타입화된 래퍼가 있는 도구에 CmdTasks.exec를 그대로 두는
것은 바로가기가 아닌 버그입니다. && 체인은 순차적 단계가 되고,
run/전제 조건 위임은 .dependsOn(...)이 되며, 파이프, 리디렉션, 환경 변수 할당처럼
쉘 특화되어 번역할 수 없는 것은 // TODO 뒤에 보존되어 파일이 여전히 컴파일됩니다.
setup과 정확히 같이 런처와 deno.json을 스캐폴딩하며, 동일한 --dir, --name,
--force, --yes 플래그를 사용합니다. 이후 zuke-write-build 스킬을 사용하여
남아 있는 생성된 CmdTasks.exec 호출을 타입화된 *Tasks 래퍼로 대체하세요.
zuke setup이 작성하는 파일
zuke.ts— 샘플 타겟과default가 포함된 시작용 빌드 클래스../zuke+./zuke.ps1— 프로젝트를 찾고PATH에 있는 Deno로zuke.ts를 실행하는 런처. Deno가 없으면 공식 설치 문서를 가리키며, 인증되지 않은 코드를 다운로드하여 실행할 수 있는 쉘 스크립트를 실행하지 않고 종료합니다.deno.lock이 존재하면--frozen을 전달하여 첫 번째 실행 시 잠금 파일을 쓰고 이후 모든 실행 시 검증합니다.deno.json—zuke태스크를 추가하고, 없으면fmt/lint/test도 추가하여 병합합니다. 병합은 전부 아니면 전무입니다:zuke태스크가 이미 선언되어 있으면 파일을 완전히 건드리지 않으며, 파싱 불가능한 파일은 알림과 함께 건너뜁니다.zuke.json—{ "name": "..." }으로 저장소 루트를 표시합니다..gitignore— 생성되거나 추가되어.zuke/가 무시되도록 합니다(캐시와 지속적인 실행 상태가 그곳에 저장됨); 이미 포함되어 있으면 건드리지 않습니다.
빌드 실행하기
./zuke # 기본 타겟 실행 (Windows: .\zuke.ps1)
./zuke <타겟> # 특정 타겟 실행
./zuke --list # 모든 타겟 나열
./zuke --list --json # 전체 빌드 표면(명령어, 플래그, 타겟)을 JSON으로 출력
./zuke <타겟> --dry-run # 실행하지 않고 계획만 출력
CLI는 자체 문서화되어 있습니다: ./zuke --help는 사용법 문법과 빌드의 실시간
타겟 및 매개변수를 출력하므로, 에이전트가 추측 대신 실제 명령어 표면을 발견할 수
있습니다. AI 클라이언트가 타입화된 호출을 통해 빌드를 조작하려면,
zuke mcp가 Model Context Protocol 서버를 실행합니다 (claude mcp add zuke -- deno run -A zuke.ts mcp;
--allow-run을 추가하면 에이전트가 타겟을 검사뿐만 아니라 실행할 수 있습니다).
Deno가 이미 설치되어 있으면 deno task zuke <타겟> 또는
deno run -A zuke.ts <타겟>을 사용할 수도 있습니다. -A 플래그는 권한을 부여하며,
타겟이 일반적으로 프로세스를 실행하고 파일을 다루기 때문입니다. 이는 런처와 완전히
동일하지 않습니다: 스캐폴딩된 zuke 태스크는 의도적으로 --frozen을 생략하여
./zuke가 실패할 오래된 잠금 파일을 복구할 수 있습니다.
수동 설정 (CLI 없음)
프로젝트 루트에 zuke.ts를 만들고, Build를 확장하고, target()으로 타겟을
선언하고, 아래쪽에서 await run(MyBuild)를 호출하세요:
import { Build, run, target } from "jsr:@zuke/core";
import { DenoTasks } from "jsr:@zuke/deno";
class CI extends Build {
lint = target().executes(() => DenoTasks.lint());
test = target().dependsOn(this.lint)
.executes(() => DenoTasks.test((s) => s.allowAll()));
default = target().dependsOn(this.test).executes(() => {});
}
await run(CI);
deno run -A zuke.ts test로 실행하세요. (./zuke 런처 경험을 원한다면
zuke setup을 선호하세요. 런처 스크립트를 자동으로 생성합니다.)
정확한 API 찾기 — 절대 추측하지 마세요
모든 외부 도구에는 타입화된 *Tasks 래퍼가 있습니다. Deno.Command나 수동
쉘 명령어로 대체하지 마세요. 먼저 래퍼가 존재하는지 확인하세요 —
llms.txt의 ## Packages 카탈로그 또는
zuke-write-build의 요약표만이
이를 알 수 있는 유일한 방법입니다. 패키지별 deno doc은 대상 이름이 필요하므로
래퍼의 존재를 알 수 없습니다. 패키지 이름을 알게 되면 정확한 시그니처를 얻으세요:
- 명령줄에서 단일 패키지:
deno doc jsr:@zuke/<패키지>. 소비자 저장소에서 이것을 선호하세요 — 프로젝트에 실제 설치된 버전을 해결하므로 존재하지 않는 API를 설명할 수 없습니다. - 모든 패키지의 전체 타입화된 표면은 **
llms-full.txt**에 있습니다 (llms.txt로 인덱싱) — Zuke 저장소 자체의 루트에 있거나, 소비자 저장소에서 https://raw.githubusercontent.com/zuke-build/zuke/master/llms-full.txt (인덱스: https://raw.githubusercontent.com/zuke-build/zuke/master/llms.txt). 둘 다master를 추적하므로 병합되었지만 아직 릴리스되지 않은 심볼을 문서화할 수 있습니다. 존재하는 것을 찾은 다음deno doc으로 시그니처를 확인하세요.
프로젝트가 스캐폴딩되면 zuke-write-build 스킬을 사용하여 타겟을 추가하고 수정하세요.