Dokumentacja Markpact

Słownik pojęć, skrótów i przepływów w ekosystemie Markpact.com — portal, Python CLI, redeploy i opcjonalni konsumenci (urisys, nl2uricore).

Tutorial — scenariusze Dokumentacja API Zaloguj się

Format i pliki

PojęcieSkrótOpis
Markpact — Plik markdown (*.markpact.md) opisujący paczkę URI: metadane, capabilities i opcjonalny kod handlerów. Portal go przechowuje i udostępnia przez raw URL — nie wykonuje kodu z pliku.
Przykład
        uricache.markpact.md
UriPack UP Formalny typ paczki w ekosystemie urisys. W pliku Markpact deklarujesz go w bloku ```yaml markpact:pack``` z kind: UriPack.
markpact:pack blok YAML Obowiązkowy fenced block w pliku Markpact. Portal sprawdza jego obecność i pole kind: UriPack przed publikacją.
Przykład
        ```yaml markpact:pack
apiVersion: urisys.io/v1
kind: UriPack
...
scheme URI scheme Prefiks URI obsługiwany przez paczkę, np. cache, http, custom. W Markpact ustawiasz go w metadata/scheme lub w capabilities.
Przykład
        cache://default/query/status
capability cap Pojedyncza operacja URI zdefiniowana w paczce: uri, kind (query/command), handler.
raw URL raw Bezpośredni link HTTP do pliku markdown bez HTML portalu. Używany przez curl, watchery redeploy, CI i opcjonalnych konsumentów (urisys).
Przykład
        https://markpact.com/raw/owner/pack.markpact.md

Narzędzia i skróty

PojęcieSkrótOpis
markpact:deps blok deps Blok JSON z runtime i pakietami Python — dla pipeline'ów deploy/redeploy.
Przykład
        ```json markpact:deps\n{"runtime":"python:3.12","packages":["fastapi","uvicorn"]}\n```
markpact:run blok run Blok z komendą shell wykonywaną lub obserwowaną przez narzędzia redeploy po pobraniu raw_url.
Przykład
        ```bash markpact:run\nuvicorn app.main:app --host 0.0.0.0 --port 8000\n```
redeploy — Workflow konsumenta: obserwacja raw_url (lub polling), odczyt markpact:deps/run, przebudowa i restart po republish.
urisys — Opcjonalny runtime URI — jeden z wielu konsumentów. Pobiera UriPack i uruchamia handlery w sandboxie.
Przykład
        urisys markpact fetch https://markpact.com/raw/owner/pack.markpact.md
nl2uricore n2u Opcjonalny generator — tworzy UriPack z promptu. --publish markpact.com wysyła na portal przez API.
Przykład
        nl2uricore generate --publish markpact.com --out uricache.markpact.md
markpact CLI markpact Główny lokalny klient Python (public/client/markpact.py). Instalacja: curl install.sh. Komendy: init, publish, keys, me.
Przykład
        markpact publish todo-api.markpact.md
install_command download cmd Gotowa komenda curl zwracana przez API po publikacji — pobiera plik raw markdown.
Przykład
        curl -fsSL https://markpact.com/raw/owner/pack.markpact.md -o pack.markpact.md

Portal markpact.com

PojęcieSkrótOpis
owner_slug owner Identyfikator właściciela paczki w URL, zwykle pochodzący z części e-maila przed @.
Przykład
        /p/adam/uricache → owner=adam
pack_slug pack Nazwa paczki w URL i w metadata.id pliku Markpact.
Przykład
        /p/adam/uricache → pack=uricache
Git-backed registry Git repo Każda publikacja zapisuje plik w storage/repo/packs/<owner>/ i opcjonalnie robi git commit (gdy git i shell_exec są dostępne).
Dashboard panel Panel użytkownika po zalogowaniu: tokeny API, CLI, klucze SSH.

API i autoryzacja

PojęcieSkrótOpis
API token mp_ Bearer token do POST /api/publish i /api/me. Prefix mp_. Generowany w dashboardzie, pokazywany tylko raz.
Przykład
        Authorization: Bearer mp_...
Bearer auth JWT-like Nagłówek HTTP Authorization: Bearer <token>. Alternatywa: X-Markpact-Token.
OpenAPI OAS Specyfikacja maszynowa API pod /api/openapi.json. Dokumentacja HTML: /api/docs.

Bezpieczeństwo

PojęcieSkrótOpis
SSH-signed publish SSH sig Publikacja bez Bearer token — podpis ssh-keygen -Y sign nad kanoniczną wiadomością markpact-publish-v1. Weryfikacja kluczem publicznym z dashboardu.
fingerprint SHA256 Skrót klucza publicznego SSH (SHA256:...). Identyfikuje klucz przy publish-signed.
OTP login 6-digit Logowanie do portalu jednorazowym 6-cyfrowym kodem wysyłanym e-mailem. Sesja odnawiana przy aktywności, wygasa po 31 dniach.
Sandbox execution — Kod Python z bloków markpact:handler nie jest uruchamiany na serwerze portalu. Wykonanie należy do konsumentów (redeploy, urisys) po stronie klienta.

Przepływ publikacji

Typowy scenariusz od lokalnej edycji do użycia (aplikacja Python, redeploy lub runtime URI):

Schemat krok po kroku
        1. Piszesz lub generujesz *.markpact.md lokalnie
   (markpact publish file.markpact.md — główne CLI)

2. Portal waliduje yaml markpact:pack
   zapisuje storage/repo/packs/<owner>/<pack>.markpact.md
   opcjonalnie: git commit

3. API zwraca raw_url + install_command (curl download)

4. Konsumenci pobierają raw_url:
   · watcher redeploy (markpact:deps / markpact:run)
   · narzędzia Python / CI
   · urisys markpact fetch (opcjonalny runtime URI)

Skróty w pigułce

  • mp_ — prefix tokenu API
  • UP / UriPack — typ paczki URI
  • raw — bezpośredni URL pliku .markpact.md
  • owner/pack — ścieżka paczki w registry
  • SSH sig — publikacja podpisana kluczem zamiast Bearer
  • OAS — OpenAPI spec pod /api/openapi.json