Tutorial · Markpact

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

Zaloguj się na portal

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

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

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'

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
        
      
```
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

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
```

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'

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

Edytuj bloki deps lub run

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

Republikuj przez markpact CLI

Zachowaj metadata.id — raw URL pozostaje ten sam.

Republish

        markpact publish todo-api.markpact.md

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

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'
        
      
```
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)

Przygotuj plik Markpact

Plik musi mieć poprawny blok markpact:pack (kind: UriPack) i unikalne metadata.id (pack slug).
Otwórz formularz publikacji

Wejdź na https://markpact.com/publish. Opcjonalnie name i description — nadpisują metadane z pliku.
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

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

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

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_...)

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...\`\`\`"}'

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"

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

Skonfiguruj token

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

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

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

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

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

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

Zachowaj metadata.id

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

Preferowane: markpact publish. Także: formularz web, REST API lub SSH.
Republish
```
        markpact publish todo-api.markpact.md
        
      
```

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

Tutorial Markpact

Szybki start: lokalne CLI markpact

Zaloguj się na portal

Wygeneruj token API

Zainstaluj lokalne CLI markpact

Opublikuj plik Markpact

Pobierz lub użyj raw URL

Aplikacja Python z blokami deps i run

Struktura pliku Markpact

Publikacja z maszyny

Weryfikacja na portalu

Redeploy po zmianie markdown

Edytuj bloki deps lub run

Republikuj przez markpact CLI

Odśwież konsumentów

Biblioteka Python / metadata paczki

Przygotuj mylib.markpact.md

Udostępnij raw URL

Publikacja przez przeglądarkę

Przygotuj plik Markpact

Otwórz formularz publikacji

Wyślij plik lub wklej markdown

Publikacja podpisana SSH (CI / bez Bearer)

Wygeneruj klucz (jednorazowo)

Publikacja z podpisem

Przykład GitHub Actions

Publikacja przez REST API (curl)

Publikacja JSON

Upload pliku (multipart)

Lista paczek (publiczna)

Generowanie paczki z nl2uricore (opcjonalnie)

Skonfiguruj token

Generuj i publikuj

Sprawdź wynik

Użycie paczki w urisys (opcjonalny konsument)

Pobierz paczkę

Wywołaj URI z paczki

Odśwież po republish

Aktualizacja istniejącej paczki

Zachowaj metadata.id

Opublikuj ponownie

Odśwież konsumentów