Skip to content

GETTING-STARTED.md

Latest commit

 

History

History
170 lines (130 loc) · 7.47 KB

GETTING-STARTED.md

File metadata and controls

170 lines (130 loc) · 7.47 KB
Raw

BarShelf 시작하기

이 문서는 BarShelf을 설치하고, 3분 안에 첫 셸 위젯을 추가한 뒤, 번들 위젯을 둘러보기 위한 빠른 안내다.

관련 문서:

설치

전체 설치 방법(릴리스 zip, Gatekeeper 안내, barshelf CLI, 문제 해결)은 docs/INSTALL.md를 따른다. 요약:

GitHub Releases (권장)

Releases에서 BarShelf-<버전>-arm64.zip을 받아 /Applications에 옮긴 뒤 일반 더블클릭으로 실행한다. v0.1.3은 Developer ID 서명·Apple 공증·티켓 스테이플과 Gatekeeper 배포 검사를 통과했다.

소스에서 수동 빌드

이 저장소에서 직접 빌드할 때는 Xcode 툴체인을 명시한다.

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer bash scripts/build_app.sh
open dist/BarShelf.app

scripts/build_app.sh는 SwiftPM product barshelf-app을 release로 빌드하고, dist/BarShelf.app/Contents/MacOS/barshelf-app 실행 파일과 Contents/Info.plist를 만든 뒤 widgets/를 앱 리소스로 복사한다. 같은 빌드에서 dist/barshelf와 dist/bsf CLI도 생성된다. 개발 중 검증은 다음 명령을 사용한다.

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test

코드 없이 위젯 만들기: Widget Builder

JSON을 직접 작성하지 않고도 위젯을 만들고 싶다면 in-app Widget Builder를 사용한다. 메뉴바의 BarShelf 아이콘을 우클릭하고 **Create Widget…**을 선택하면 열린다.

3단계로 진행한다.

  1. Source — 데이터 출처를 고른다: 셸 명령, HTTP JSON, 붙여넣은 JSON, 폴더 파일 목록, 고정 텍스트 중 하나. 명령은 Test run, HTTP는 Fetch preview로 출력 구조를 확인할 수 있다.
  2. Display — 결과를 목록, 표, 값, 텍스트 중 어떤 모습으로 보여줄지 고른다. JSON이면 감지된 필드를 드롭다운에서 골라 매핑하고, 오른쪽 미리보기 패널에 실제 렌더링 결과가 즉시 반영된다.
  3. Details — 이름, 아이콘, Panel, 크기, 고급 새로고침 주기를 정하고 Create를 누르면 위젯이 바로 만들어진다.

코드를 한 줄도 쓰지 않고 셸 명령이나 폴더 기반 위젯을 몇 분 안에 만들 수 있는 가장 빠른 경로다. manifest와 workflow JSON을 직접 다루는 방법을 배우고 싶다면 아래 튜토리얼을 계속 읽는다.

3분 위젯: Quick Hello

BarShelf은 개발 중 ./widgets/를 먼저 보고, 사용자 설치 위젯은 ~/Library/Application Support/barshelf/widgets/에서 읽는다. 아래 예제는 사용자 설치 경로에 새 위젯을 만든다.

install_root="$HOME/Library/Application Support/barshelf/widgets/dev.example.quick-hello"
mkdir -p "$install_root"

widget.json을 만든다.

cat > "$install_root/widget.json" <<'JSON'
{
  "$schema": "https://barshelf.jiun.dev/schema/widget-0.1.json",
  "schemaVersion": 1,
  "id": "dev.example.quick-hello",
  "name": "Quick Hello",
  "version": "0.1.0",
  "icon": "hand.wave",
  "bucket": { "group": "Demo", "order": 11, "size": "S" },
  "entry": { "kind": "exec" },
  "source": {
    "kind": "exec",
    "command": ["./hello.sh"],
    "timeoutMs": 5000,
    "output": "viewtree"
  },
  "refresh": { "onOpen": true, "interval": 60, "staleAfterSec": 30 },
  "permissions": {
    "exec": [
      {
        "command": "./hello.sh",
        "allowedArgs": [[]],
        "maxOutputBytes": 65536,
        "sensitiveOutput": false
      }
    ],
    "network": [],
    "readPaths": [],
    "env": [],
    "keychain": false
  },
  "settings": []
}
JSON

실행 파일을 만든다.

cat > "$install_root/hello.sh" <<'SH'
#!/usr/bin/env bash
set -euo pipefail

now="$(date '+%H:%M:%S')"
second="$(date '+%S')"
progress="$(printf '0.%02d' "$((10#$second))")"

cat <<JSON
{
  "type": "vstack",
  "spacing": 8,
  "children": [
    { "type": "text", "role": "title", "text": "Quick Hello" },
    { "type": "text", "role": "body", "monospacedDigit": true, "text": "Rendered at ${now}" },
    { "type": "progress", "style": "linear", "value": ${progress}, "label": "Minute", "tint": "accent" },
    {
      "type": "button",
      "title": "Copy greeting",
      "icon": "doc.on.doc",
      "action": { "type": "copyText", "value": "Hello from BarShelf at ${now}", "toast": "Copied" }
    }
  ]
}
JSON
SH

chmod +x "$install_root/hello.sh"

앱이 실행 중이면 hot reload가 자동으로 반영된다. 팝오버를 열고 Quick Hello 권한 승인 카드에서 Approve를 누르면 위젯이 실행된다.

번들 위젯

저장소의 widgets/에는 개발과 검증에 쓰는 번들 예제가 들어 있다.

위젯 위치 설명
Hello widgets/hello ./hello.sh가 UINode JSON을 stdout으로 출력하는 가장 작은 exec 위젯이다.
aas Usage widgets/aas-usage aas usage --json 결과를 aas-usage 내장 adapter로 렌더링한다.
OTP Codes widgets/otpeek otpeek list --json과 otpeek code <id> --json을 사용하고 Keychain 주입을 지원한다.
Script Clock widgets/clock-script Deno TypeScript 런타임과 sdk/mod.ts를 사용하는 script 위젯이다.
Recent Files widgets/recent-files workflow.json으로 ~/Downloads 파일 목록, 썸네일, Finder 표시 액션, drag-out을 렌더링한다.

기본 조작

  • 메뉴바 아이콘을 클릭하면 팝오버가 열린다.
  • 좌우 화살표, 하단 점, 두 손가락 가로 스와이프로 Panel 페이지를 전환한다.
  • Command-1부터 Command-9까지는 페이지로 바로 이동한다.
  • Command-F 또는 타이핑으로 검색을 연다.
  • 위젯 카드 우클릭 메뉴에서 pin, settings, refresh 등을 사용할 수 있다 (자세한 목록은 아래 "위젯 관리" 참고).
  • drag.filePath가 있는 파일 노드는 Finder나 다른 앱으로 드래그할 수 있다.

위젯 관리

위젯 카드를 우클릭하면 다음 메뉴가 나온다.

  • Pin: 위젯을 상단에 고정해 페이지를 넘겨도 계속 보이게 한다.
  • Settings: 위젯별 설정 화면을 연다.
  • Disable: 삭제하지 않고 새로고침과 팝오버 노출만 끈다.
  • Move to Panel: 다른 Panel로 옮기거나 새 Panel 이름을 입력해 만든다.
  • Reveal in Finder: 위젯이 설치된 디렉터리를 Finder로 연다.
  • Remove: 확인 후 위젯 디렉터리와 관련 상태(pin, 설정, 새로고침 기록 등)를 모두 삭제한다.

메뉴바 아이콘 우클릭 → Settings로 여는 설정 창의 Widgets 탭에서도 전체 위젯을 한 목록으로 보면서 활성화/비활성화, Panel 이동, 드래그 순서 변경, 삭제를 관리할 수 있다.