콘솔 사용법¶

windforce 콘솔은 브라우저에서 앱을 만들고, 코드를 배포하고, 잡 실행을 관찰하고, 워크스페이스를 운영하는 화면이다. 이 페이지는 로그인부터 Jobs 관찰, Apps 생성, 편집기에서의 저작·배포, 워크스페이스 Settings까지 주요 화면을 순서대로 안내한다.

로그인과 가입¶

로그인 화면

/login에서 이메일과 비밀번호로 로그인한다. 실패하면 서버가 보낸 에러 메시지가 그대로 화면에 표시된다.
Create account로 가입하면 즉시 로그인된다. 셀프서비스 가입은 이메일 검증이 필요하다 — 온보딩 화면에 "이메일을 확인하세요" 안내와 재발송 버튼이 뜨고, 확인 메일의 링크를 열기 전까지 워크스페이스 생성이 잠긴다. 초대로 가입한 경우엔 초대 자체가 주소를 증명하므로 검증이 필요 없다.
검증이 끝나면 온보딩 화면에서 자기 워크스페이스를 직접 생성한다. 워크스페이스 id는 URL에 쓰이므로 소문자/숫자/하이픈만 허용되고 이후 변경할 수 없다. 생성하는 즉시 그 워크스페이스의 admin이 되어 첫 앱 연결 화면으로 이동한다.
로그인하면 기본 워크스페이스의 Apps 화면으로 이동한다. 아직 앱이 없으면 "Connect your first app" 안내가 위저드로 이끈다.

비밀번호 재설정¶

로그인 화면의 Forgot password에 이메일을 제출하면 계정 존재 여부와 무관하게 항상 "요청 접수" 안내가 표시된다. 계정이 있으면 재설정 링크가 메일로 발송된다(서버에 SMTP 구성이 필요).
메일의 링크는 30분 유효·1회용이다. 새 비밀번호(8자 이상)를 확인 입력과 함께 제출한다.
성공하면 기존 로그인 세션이 모두 로그아웃되고, 새 비밀번호로 다시 로그인한다.

초대 받기¶

워크스페이스 admin이 보낸 초대 메일의 링크로 들어오면 초대 전용 화면이 뜬다 — 어느 워크스페이스에 어떤 역할로 초대됐는지 보여준다.
계정이 없으면 그 자리에서 가입한다(이메일은 초대된 주소로 고정). 이미 계정이 있으면 로그인 탭에서 로그인한다.
Accept invitation을 누르면 즉시 멤버가 되어 그 워크스페이스로 이동한다. 초대는 7일 유효·1회용이며, 초대된 주소로 로그인한 계정만 수락할 수 있다.

워크스페이스 셸¶

로그인 후 모든 화면은 좌측 사이드바가 고정된 셸 안에서 열린다.

좌측 사이드바는 항상 화면에 고정되고 본문만 스크롤된다. 하단 Collapse로 아이콘만 남게 접을 수 있으며, 접힘 상태는 브라우저에 기억된다.
상단 워크스페이스 스위처를 클릭하면 내가 속한 모든 워크스페이스 목록이 열린다. 클릭으로 전환하고, Create workspace로 셸 안에서 바로 새 워크스페이스를 만든다.
메뉴는 Apps / Jobs / Workers / Settings다. 하단 계정 영역을 클릭하면 Account settings(비밀번호 변경)와 Sign out이 열린다. admin 권한 여부에 따라 Settings의 관리 기능과 앱의 배포 기능 노출이 달라진다.
멤버가 아닌 워크스페이스 URL로 들어가면 접근 불가 화면이 표시된다(리다이렉트 없이 URL을 점검할 수 있다).

Jobs — 실행 관찰¶

Jobs 화면은 워크스페이스에서 일어난 잡 실행의 목록과 상세를 보여준다.

Jobs 목록

상태 칩: 목록 위의 All / Queued / Running / Failed / Succeeded / Canceled 칩이 실시간 카운트를 함께 보여준다. 클릭 한 번으로 필터가 걸린다. App·Window 필터와 조합되며 모두 URL에 반영되므로 "demo 앱의 실패만" 같은 화면을 링크로 공유할 수 있다.
목록은 항상 최근 창이다: 기본 Last 24 hours 시간창(1h / 24h / 7d / 30d / All time 중 선택) 안에서 최신순 50건씩 보여준다. 목록 위 캡션이 지금 보이는 범위를 항상 알려준다.
Load older runs로 더 오래된 기록을 이어서 불러온다. 커서 기반이라 페이지를 넘기는 동안 새 잡이 들어와도 행이 밀리거나 중복되지 않는다. 누적 1,000건에 도달하면 필터·시간창을 좁히라는 안내로 전환된다.
보존 한도: 완료(성공/실패/취소) 잡과 그 로그는 기본 30일이 지나면 자동으로 정리된다(인스턴스 설정에 따라 다르며, 목록 하단에 현재 한도가 항상 표시된다). 큐에 있거나 실행 중인 잡은 삭제되지 않는다. 장기 보관이 필요하면 만료 전에 결과를 따로 내보낸다.
진행 중(queued/running) 잡이 보일 때만 화면이 자동 갱신된다. Created 시각은 상대시각("3m ago")으로 표시되고 hover로 절대시각을 확인한다.

Job 상세

행의 app/action 링크를 누르면 잡 상세로 들어간다.

Details: enqueue 시점에 고정된 실행 메타(commit·entrypoint·tag·worker·시각·duration·생성자).
Input: 이 잡이 받은 입력 JSON — 재현과 디버깅의 출발점.
Result: 성공 시 결과 JSON, 실패/취소 시 에러 name과 message.
Logs: 실행 중에는 라이브로 따라가고, 완료 시 마지막까지 반영된다.
Run again: 완료된 잡을 같은 입력으로 재실행하고 새 잡 상세로 이동한다 — 일시 장애 재시도나 수정 배포 후 재검증에 쓴다.
Cancel job: queued 잡은 즉시 취소되고, running 잡은 워커가 감지한 뒤 종료된다. 워크스페이스 admin 또는 잡 생성자만 가능하다.
queued인데 안 도는 잡: 그 tag를 서빙하는 라이브 워커가 없으면 상세 화면이 경고로 알려주고 워커 커버리지로 안내한다.

Apps — 카탈로그와 앱 생성¶

Apps 화면은 로그인 후의 기본 랜딩이며, 워크스페이스의 모든 앱을 카탈로그로 보여준다. 앱 하나는 하나의 git source와 1:1로 연결된다 — 소스의 windforce.json manifest가 앱 하나를 선언하고, 앱은 그 소스를 sync한 결과물이다.

Apps 카탈로그

주의 신호 밴드: 화면 상단에 지금 주의할 일만 카드로 뜬다 — 최근 24시간 실패, 미서빙 태그에 쌓인 queued, 현재 running. 카드를 클릭하면 해당 필터가 걸린 Jobs/Workers로 바로 이동한다. 신호가 없으면 밴드가 보이지 않는다.
카탈로그: 앱별 현재 배포 커밋과 활동 지표(지금 running/queued 잡 수, 최근 24시간 실패 수)를 보여준다. 검색과 정렬(이름·최근 갱신·실패 우선)로 좁힌다. 앱을 클릭하면 상세로 간다.
Pending sources: 초기 sync가 실패해 아직 앱이 되지 못한 소스만 여기 보인다 — 저장소나 manifest를 고친 뒤 Retry sync, 또는 Remove.

앱 생성 — 두 갈래¶

우상단 Create app은 생성 페이지로 이동한다. 두 경로가 탭으로 갈린다.

Create app

Start coding(기본) — git을 직접 만들거나 연결하지 않고 앱 이름과 스타터 템플릿만 고르면, 플랫폼이 뒤에서 관리형 git 저장소를 자동 생성하고 곧장 편집기로 들어간다. 템플릿은 Blank(hello 액션 하나), HTTP webhook(요청 body·headers를 받는 핸들러), Scheduled job(상태를 커서로 쓰는 주기 잡) 중에서 고른다. 입력한 이름은 app_key로 변환돼 미리 표시된다(소문자/숫자/_, 첫 글자는 영문). 이후 편집·배포는 일반 앱과 같다. git은 플랫폼이 관리하므로 설정·상세에서 보이지 않고 "platform-managed"로 표시된다.
Connect a git repo(고급) — 이미 manifest가 있는 저장소를 연결하는 3단계 위저드다.
Repository — 저장소 URL(+branch/subpath)을 입력한다. Connect & sync는 먼저 원격을 점검해 도달성·브랜치 존재를 검증하므로 오타는 소스가 만들어지기 전에 잡힌다. Access token(선택)은 프라이빗 저장소 읽기나 콘솔에서의 push에 필요하며 워크스페이스 시크릿으로 암호화 저장된다. 공개 read-only 저장소면 비워 둔다.
Sync — 연결과 초기 sync가 진행된다. 실패하면 원인과 함께 Retry sync 또는 Keep as pending & exit를 고른다.
Ready — 발견된 actions와 sync 커밋 요약을 확인하고 Open app으로 들어간다.

App 상세¶

앱의 모든 기능은 상세 화면의 탭(Overview · Actions · Triggers · Deploy · Settings)에 모여 있다.

Overview: 배포 메타(commit·entrypoint·tag·timeout·concurrency)와 이 앱이 인제스트되는 Source 카드(Sync now 포함), 그리고 최근 잡 5건을 보여준다.
Actions: action별 tag와 timeout을 보여준다. Run을 누르면 action에 input schema가 있을 때 필드 폼이 자동 생성된다(필수 표시·기본값·설명 힌트, 제출 전 타입 검증) — 스크립트를 몰라도 실행할 수 있다. 스키마가 없거나 복잡하면 JSON 입력으로 폴백되고, 폼↔JSON을 토글해도 입력값은 보존된다. Webhook 버튼은 외부 시스템이 이 action을 호출할 엔드포인트와 자격을 발급·회수한다(admin).
Triggers: action을 호출하는 모든 방법을 한곳에 모은다. 항상 존재하는 API / Webhook / Manual 엔드포인트와, 콘솔이 명시적으로 만드는 Schedules(cron 주기 자동 실행)를 관리한다. 스케줄은 표준 5필드 cron 또는 @hourly·@daily·@every 30m 같은 디스크립터에 timezone과 input을 곁들여 만들고, 인라인으로 편집하거나 Pause/Resume한다.
Settings(admin 전용): Source(소스 설정·Access token), Runtime(timeout·max concurrent 슬라이더와 라우팅 override), Danger zone(앱 삭제) 서브탭으로 나뉜다.

Draft와 Deploy¶

콘솔에서 코드를 바꾸는 흐름은 draft를 저장하고 → Deploy하는 두 단계다. draft는 "배포될 전체 소스 번들"의 작업본일 뿐이며 실행과는 무관하다. Deploy를 눌러야 git에 커밋·푸시되고, 그 커밋이 sync된 뒤에야 카탈로그(실제로 실행되는 코드)가 바뀐다.

App 상세 Deploy 탭

Deploy 탭(저작은 admin 전용)은 저장된 draft 요약(파일 수·base commit·갱신 시각)과 Open editor 진입점, Discard, 그리고 버전 History를 보여준다. 외부에서 직접 push한 배포는 external_sync, 콘솔에서 한 배포는 cp_deploy로 구분된다.
실제 저작은 전체화면 편집기에서 한다.

배포 상태는 pending → committed → syncing → deployed / failed 순으로 진행되며, deployed에 도달해야 카탈로그·history·actions가 갱신된다.

flowchart TD
  EDIT["편집기에서 소스 수정"] --> SAVE["Save draft<br/>(실행과 무관한 작업본)"]
  SAVE --> DEPLOY["Deploy<br/>(commit message 입력)"]
  DEPLOY --> GIT["git commit + push"]
  GIT --> SYNC["sync / materialize"]
  SYNC --> CATALOG["카탈로그 갱신<br/>(이때부터 새 코드 실행)"]

Read-only 원격: push 자격증명 없이 연결된 공개 http(s) 저장소는 콘솔 deploy가 push 단계에서 거부된다. 편집기는 Read-only remote 배지를 띄우고 Deploy를 비활성화한다. 코드 열람·draft 저장·아래의 Run preview는 그대로 가능하며, 변경은 저장소에 직접 push한 뒤 Sync now로 반영한다. 콘솔 deploy까지 쓰려면 소스에 push 가능한 자격증명을 설정한다.

편집기 — 저작·미리보기·배포¶

Open editor는 셸을 벗어난 전체화면 편집기로 이동한다. TS/JSON 하이라이트에 더해 windforce 클라이언트 타입이 주입돼 ctx. 자동완성·시그니처 도움말·타입 에러가 살아 있는 작업 공간이다. draft가 없으면 빈 캔버스가 아니라 현재 배포 커밋의 소스가 그대로 열린다 — 지금 돌고 있는 코드에서 시작한다.

전체화면 편집기

좌측 activity bar로 Explorer와 Source Control 패널을 전환한다. Explorer에서 배포될 전체 소스 번들(windforce.json, 엔트리포인트, 스키마)을 추가/편집/삭제한다. 새 파일은 하단 입력에 schemas/new.json처럼 전체 경로로 추가한다. 수정하면 상단에 Unsaved changes가 표시된다.
Save draft로 미완성 번들도 저장된다(manifest·schema 검증은 deploy 단계에서 한다). Discard draft는 draft를 버리고 현재 배포 소스로 되돌린다.
파일을 열면 상단에 탭으로 쌓여 여러 파일을 오간다. .md 파일은 우상단 Preview 토글로 Mermaid 다이어그램까지 포함한 미리보기를 켠다. 맨 아래 상태바는 base commit·변경 수·읽기전용 여부·활성 파일의 경로/언어/저장 상태를 보여준다.

Run preview — 배포 없이 실제 실행¶

상단 Run 토글은 우측 sheet를 연다. draft manifest 기준으로 action을 고르고(아직 배포하지 않은 새 action도 보인다) 입력 폼(또는 JSON)에 값을 넣어 Run하면 저장된 draft 스냅샷이 실제 워커에서 실행된다(미저장 변경은 먼저 자동 저장된다).

Run preview — 우측 sheet 결과와 아래 Console

결과 JSON은 우측 sheet에, 콘솔 로그는 편집기 아래 Console 패널에 인라인으로 흐른다. Console은 sheet를 닫아도 유지되어 편집하면서 출력을 본다.
preview 잡은 Jobs 목록에 preview로 보이며 카탈로그나 배포 이력에는 아무것도 남기지 않는다. read-only 원격이어도 preview는 가능하다 — 막히는 것은 deploy뿐이다.

Diff — 배포본 대비 무엇을 바꿨나¶

activity bar의 Source Control 아이콘은 배포본 대비 draft 변경을 파일별로 보여준다(A/M/D 배지로 추가·수정·삭제 구분). 항목을 클릭하면 메인 영역이 배포본 ↔ draft 좌우 diff로 바뀌어 deploy 전에 변경 내용을 확인할 수 있다.

Source Control 패널의 diff

패널 하단의 Deploy 버튼은 배포 sheet를 연다.
Open in VS Code 버튼은 딥링크로 로컬 VS Code에 저장소를 clone한다 — git이 정본이므로 풀 IDE 경험은 로컬에서 이어간다.

Intellisense — `ctx.` 자동완성과 타입 검사¶

편집기는 스크립트 언어별로 플랫폼 계약(ctx.)을 가볍게 검사한다.

ctx 자동완성과 시그니처 도움말

TypeScript: windforce 클라이언트 타입이 주입돼 ctx. 자동완성·시그니처 도움말·타입 에러가 동작한다. 번들 내 파일끼리의 상대 import는 물론, 다른 npm 패키지를 import해도 타입을 자동으로 가져와 인식한다 — 타입이 도착하면 빨간 줄이 사라진다.
Python(.py): 문법 하이라이트와 ctx. 자동완성, 그리고 알 수 없는 ctx. 멤버 경고(예: ctx.nope 오타에 노란 밑줄)를 받는다. 런타임 오류를 미리 잡는 것이 목적이며, 일반 Python 의미 타입 검사는 범위 밖이다.
Go(.go): 같은 방식으로 문법 하이라이트와 ctx. 자동완성(Input·Logger·Variables 같은 PascalCase 멤버), 알 수 없는 멤버 경고를 받는다 — 워커 빌드에서 컴파일 에러가 될 멤버를 미리 잡는다.

배포 sheet¶

배포 sheet

sheet에서 commit message를 입력하고 Deploy하면 git에 커밋·푸시되고, 그 커밋이 sync된 뒤에야 카탈로그가 바뀐다. 완료되면 Back to app으로 복귀한다.
번들이 배포 소스와 동일하면 sheet가 "변경 없음"을 안내한다(이때는 보통 Sync now가 맞는 버튼이다).
409 conflict는 draft의 base commit 이후 외부 push가 있었다는 뜻이다 — 소스를 다시 sync한 뒤 새 base에서 draft를 다시 저장한다.

Settings — 워크스페이스·멤버·토큰·사용량¶

Settings는 Workspace / Members / API tokens / Usage 네 영역을 탭으로 나누며, 탭은 URL(?tab=)에 반영되어 링크로 공유할 수 있다.

Workspace(admin): 워크스페이스 이름을 변경한다. 변경 즉시 사이드바 스위처에 반영된다.

Members¶

Settings Members

Email invites — 표준 합류 경로다. 이메일 주소(아직 가입하지 않은 사람도 가능)와 역할을 골라 Send invite하면 초대 메일이 발송되고, 링크가 화면에도 표시돼 Copy로 직접 전달할 수 있다(SMTP가 없는 환경 포함). 열린 초대는 만료 시각과 함께 목록에 보이며 Revoke로 회수한다. 같은 주소에 열린 초대는 1건만 허용된다.
Add member directly — 초대 메일 없이 즉시 멤버십을 만든다.
역할 토글(Make admin / Revoke admin)과 Disable(확인 후 접근 즉시 차단) / Enable이 있다. 마지막 enabled admin은 강등·비활성화할 수 없다.
API tokens(admin): label과 scope를 골라 발급한다. raw 토큰은 생성 직후 1회만 표시되므로 즉시 복사해 보관한다(목록에는 prefix만 남는다). Revoke는 확인 후 즉시 적용된다.

Usage¶

Settings Usage

Usage는 최근 30일(UTC)의 잡 실행 수·실행 시간·저장량 요약과 일별 표를 보여준다. 과금 화면이 아니라 투명성 뷰다.
인스턴스에 테넌트 quota가 설정돼 있으면 같은 카운터를 quota가 읽는다 — 한도를 넘으면 새 잡 실행이 거부되거나 API 호출이 제한된다.