Tutorial Markpact

Praktyczne scenariusze: lokalne CLI markpact, aplikacje Python, redeploy, CI, API i opcjonalna integracja z urisys. Każdy krok możesz skopiować jednym kliknięciem.

Słownik pojęć Dokumentacja API Zaloguj się

Szybki start: lokalne CLI markpact

Logowanie, token API, instalacja Python CLI, publikacja pliku — standardowy workflow na markpact.com.

Wymagania:

  • Adres e-mail na allowliście portalu
  • python3 i curl na maszynie

  1. Zaloguj się na portal

    Wejdź na https://markpact.com/login, podaj e-mail i wpisz 6-cyfrowy kod z wiadomości e-mail.

  2. Wygeneruj token API

    Dashboard → Tokeny API → Wygeneruj token. Skopiuj od razu — nie będzie pokazany ponownie.

  3. Zainstaluj lokalne CLI markpact

    Jedna komenda pobiera public/client/markpact.py i zapisuje token w ~/.markpact/config.json.

    Instalacja CLI
            curl -fsSL https://markpact.com/install.sh | bash -s -- --host https://markpact.com --token 'mp_TWOJ_TOKEN'

  4. Opublikuj plik Markpact

    Plik musi zawierać blok ```yaml markpact:pack``` z kind: UriPack. Możesz też użyć formularza /publish.

    Publikacja
            markpact publish todo-api.markpact.md

  5. Pobierz lub użyj raw URL

    Po publikacji API zwraca raw_url i install_command (curl). Raw URL służy watcherom redeploy, CI, narzędziom Python — opcjonalnie urisys.

    Pobierz raw
            curl -fsSL https://markpact.com/raw/TWOJ_OWNER/todo-api.markpact.md -o todo-api.markpact.md

Aplikacja Python z blokami deps i run

Publikujesz FastAPI/Flask jako jeden *.markpact.md — typowe dla pipeline'ów redeploy.

Wymagania:

  • Zainicjalizowane lokalne CLI markpact
  • Plik z markpact:deps i markpact:run

  1. Struktura pliku Markpact

    Metadane w markpact:pack, zależności w markpact:deps, komenda startu w markpact:run.

    Przykładowy plik
            # todo-api

```yaml markpact:pack
apiVersion: markpact.io/v1
kind: UriPack
metadata:
  id: todo-api
  version: 0.1.0
```

```json markpact:deps
{"runtime":"python:3.12","packages":["fastapi","uvicorn"]}
```

```bash markpact:run
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

  2. Publikacja z maszyny

    Ten sam owner + metadata.id aktualizuje wpis w rejestrze (Git-backed).

    Publikacja
            markpact publish todo-api.markpact.md --description 'Todo REST API'

  3. Weryfikacja na portalu

    Strona paczki pokazuje raw URL (często https://{pack}.markpact.com/) i install_command (curl).

    Sprawdzenie konta
            markpact me

Redeploy po zmianie markdown

Republikujesz ten sam pack slug — watchery deploy pobierają stabilny raw URL i przebudowują.

Wymagania:

  • Istniejąca opublikowana paczka
  • Watcher deploy lub CI czytający markpact:deps / markpact:run

  1. Edytuj bloki deps lub run

    Zmień pakiety Python lub komendę startu w lokalnym *.markpact.md.

  2. Republikuj przez markpact CLI

    Zachowaj metadata.id — raw URL pozostaje ten sam.

    Republish
            markpact publish todo-api.markpact.md

  3. Odśwież konsumentów

    Narzędzia redeploy obserwują raw_url lub pollują w CI. Przykład: pobranie najnowszego markdown.

    Pull + deploy
            curl -fsSL https://markpact.com/raw/owner/todo-api.markpact.md -o todo-api.markpact.md
# skrypt deploy czyta markpact:deps i markpact:run

Biblioteka Python / metadata paczki

Publikujesz dokumentację biblioteki, handlery lub capabilities UriPack jako wersjonowany kontrakt markdown.

Wymagania:

  • Lokalne CLI markpact lub formularz /publish

  1. Przygotuj mylib.markpact.md

    Dodaj markpact:pack z unikalnym metadata.id (pack slug). Opcjonalnie bloki python handler lub deps.

    Publikacja biblioteki
            markpact publish mylib.markpact.md --name mylib --description 'Wspólne narzędzia Python'

  2. Udostępnij raw URL

    Konsumenci pobierają przez curl lub integrują raw_url w swoim toolchain — urisys nie jest wymagany.

    Raw URL
            curl -fsSL https://markpact.com/raw/owner/mylib.markpact.md

Publikacja przez przeglądarkę

Bez CLI — upload pliku *.markpact.md lub wklejenie markdown w formularzu.

Wymagania:

  • Aktywna sesja (zalogowany użytkownik)

  1. Przygotuj plik Markpact

    Plik musi mieć poprawny blok markpact:pack (kind: UriPack) i unikalne metadata.id (pack slug).

  2. Otwórz formularz publikacji

    Wejdź na https://markpact.com/publish. Opcjonalnie name i description — nadpisują metadane z pliku.

  3. Wyślij plik lub wklej markdown

    Po sukcesie zobaczysz stronę /p/{owner}/{pack} z raw URL i komendą curl.

Publikacja podpisana SSH (CI / bez Bearer)

Pipeline CI podpisuje treść kluczem prywatnym — na serwerze jest tylko klucz publiczny.

Wymagania:

  • Para kluczy ed25519
  • Klucz publiczny w Dashboard → Klucze SSH

  1. Wygeneruj klucz (jednorazowo)

    Klucz prywatny zostaje w secretach CI; klucz publiczny (.pub) rejestrujesz w portalu.

    Klucz + rejestracja
            ssh-keygen -t ed25519 -f ~/.ssh/markpact_ed25519 -N '' -C 'markpact.com'
markpact keys add ~/.ssh/markpact_ed25519.pub

  2. Publikacja z podpisem

    CLI buduje kanoniczną wiadomość markpact-publish-v1 i woła POST /api/publish-signed.

    Publikacja SSH
            markpact publish todo-api.markpact.md --ssh-key ~/.ssh/markpact_ed25519

  3. Przykład GitHub Actions

    Klucz prywatny w secrets.MARKPACT_SSH_KEY; w jobie markpact publish --ssh-key.

    CI (GitHub Actions)
            # .github/workflows/publish-markpact.yml (fragment)
- run: |
    install -m 600 "$MARKPACT_SSH_KEY" ~/.ssh/markpact_ed25519
    markpact publish packs/todo-api.markpact.md --ssh-key ~/.ssh/markpact_ed25519
  env:
    MARKPACT_SSH_KEY: ${{ secrets.MARKPACT_SSH_KEY }}

Publikacja przez REST API (curl)

Integracja z innymi narzędziami — JSON lub multipart, token Bearer.

Wymagania:

  • Token API (mp_...)

  1. Publikacja JSON

    Treść Markpact w polu content. owner_slug pochodzi z konta powiązanego z tokenem.

    POST JSON
            curl -X POST https://markpact.com/api/publish \
  -H "Authorization: Bearer $MARKPACT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"todo-api","content":"# todo-api...\n\n\`\`\`yaml markpact:pack\n...\`\`\`"}'

  2. Upload pliku (multipart)

    Wygodne dla skryptów pracujących na plikach .markpact.md.

    POST multipart
            curl -X POST https://markpact.com/api/publish \
  -H "Authorization: Bearer $MARKPACT_TOKEN" \
  -F "file=@todo-api.markpact.md" \
  -F "name=todo-api"

  3. Lista paczek (publiczna)

    Bez auth — monitoring lub mirroring.

    GET /api/packages
            curl -sS https://markpact.com/api/packages | jq '.packages[0]'

Generowanie paczki z nl2uricore (opcjonalnie)

Alternatywa dla ręcznego pisania — UriPack z promptu i publikacja od razu na portal.

Wymagania:

  • Token API w ~/.markpact/config.json lub MARKPACT_TOKEN
  • nl2uricore zainstalowany lokalnie

  1. Skonfiguruj token

    Token z dashboardu (mp_...) — przez install.sh lub export MARKPACT_TOKEN=mp_...

  2. Generuj i publikuj

    Flaga --publish markpact.com wysyła wynik na portal po walidacji. --no-llm działa bez LLM (szablon).

    nl2uricore generate
            nl2uricore generate \
  --prompt "Stwórz URI pack cache:// do statusu i komendy run" \
  --prefix cache \
  --no-llm \
  --out uricache.markpact.md \
  --publish markpact.com

  3. Sprawdź wynik

    JSON zawiera url, raw_url i install_command. Aktualizacje możesz robić też przez markpact publish.

    Sprawdzenie konta
            markpact me

Użycie paczki w urisys (opcjonalny konsument)

urisys to jeden z wielu konsumentów — pobiera capabilities UriPack i uruchamia handlery lokalnie.

Wymagania:

  • urisys z modułem markpact
  • Raw URL z portalu

  1. Pobierz paczkę

    Użyj raw URL ze strony paczki. Publikacja nadal idzie przez markpact CLI lub portal.

    urisys fetch
            urisys markpact fetch https://markpact.com/raw/owner/uricache.markpact.md

  2. Wywołaj URI z paczki

    Scheme i capabilities z Markpact — np. cache:// dla paczki cache.

    Przykładowe URI
            urisys 'cache://default/query/status'
urisys 'cache://default/command/run' --arg key=value

  3. Odśwież po republish

    urisys cache'uje skompilowaną paczkę. Ponowny fetch po zmianie raw URL na portalu.

    Ponowny fetch
            urisys markpact fetch https://markpact.com/raw/owner/uricache.markpact.md --force

Aktualizacja istniejącej paczki

Republikacja z tym samym pack slug nadpisuje plik w rejestrze (Git-backed).

Wymagania:

  • Ten sam owner (konto) co przy pierwszej publikacji

  1. Zachowaj metadata.id

    pack_slug w URL pochodzi z metadata.id w markpact:pack. Ta sama wartość = aktualizacja, nie duplikat.

  2. Opublikuj ponownie

    Preferowane: markpact publish. Także: formularz web, REST API lub SSH.

    Republish
            markpact publish todo-api.markpact.md

  3. Odśwież konsumentów

    Watchery redeploy, CI lub opcjonalnie urisys pobierają nowy markdown z tego samego raw URL.

    Pobierz najnowszy
            curl -fsSL https://markpact.com/raw/owner/todo-api.markpact.md -o todo-api.markpact.md