Poltura CLI

A @poltura/cli a poltura binárist telepíti: egyetlen eszköz az appokhoz, témákhoz, egy bolt adataihoz és az AI-eszközökhöz. Még nincs npm-en

$ npm install -g @poltura/cli

Node.js 22 vagy újabb verzió szükséges hozzá, telemetriát nem küld, és kizárólag a megadott Poltura API endpointot hívja. A poltura --help, a poltura <topic> --help és a poltura --version a CLI többi részének betöltése nélkül, egy beépített táblázatból válaszol, így azonnal lefut.

Minden parancs fogadja a -q, --quiet (csak eredmények és hibák kiírása), a --no-color és a -h, --help kapcsolókat. A NO_COLOR, FORCE_COLOR, CI változókat és a nem terminál jellegű kimenetet is figyelembe veszi. Hiba esetén kiírja a probléma okát, egy fix: vagy tipp sort, valamint egy linket az azt bemutató dokumentációs oldalra.

Bejelentkezés vagy token használataHivatkozás másolása

Hogy melyik hitelesítő adatra van szükség, attól függ, mihez nyúl a parancs:

A CLI még elküldés előtt ellenőrzi az API token checksumját, így a csonkán beillesztett token azonnal elbukik. Szervezeti tokent (plto_) nem fogad el közzétételhez, mivel azzal nem lehet közzétenni.

poltura login
poltura whoami
poltura logout

A poltura login megnyitja a Poltura ID-t a böngésződben (a --no-browser a címet írja ki helyette SSH-hoz és egyéb böngésző nélküli gépekhez), és a Poltura saját CLI-klienseként jelentkezik be OAuth és PKCE használatával, a géped egyik loopback címére érkező válasszal. Alapértelmezésben az összes olvasási jogosultságot kéri, kivéve, ha a --permissions a,b kevesebbet ad meg; a jóváhagyandó jogosultságok körét a jóváhagyási oldalon szűkítheted vagy bővítheted. A --timeout <seconds> (10-től 3600-ig, alapértelmezés: 300) határozza meg, meddig vár a CLI. A munkamenet a ~/.config/poltura/credentials.json fájlban tárolódik (0600-as jogosultsággal; a POLTURA_CONFIG_DIR áthelyezi), és még a lejárata előtt megújul. A poltura whoami megmutatja, ki vagy, mely boltokat éred el, és milyen jogosultságaid vannak ott; a poltura logout visszavonja a munkamenetet és törli az adatokat.

A bejelentkezés DPoP (RFC 9449) révén ehhez a géphez kötődik. A poltura login létrehoz egy P-256 kulcspárt, és a privát kulcsot egy saját fájlban tárolja a hitelesítő adatok mellett: dpop/<thumbprint>.pem (0600-as jogosultság). Minden tokenváltás, megújítás és API-hívás az ezzel a kulccsal aláírt igazolást hordozza, az API-hívások pedig a tokent Authorization: DPoP <token> formában küldik el. A gépről kulcs nélkül átmásolt bejelentkezési tokent a rendszer elutasítja invalid_dpop_proof hibával, és ugyanez történik a másolt frissítési tokennel is: a Poltura ID ellenőrzi a kulcsot, mielőtt bármit megújítana. Ha a kulcsfájl hiányzik, a CLI megkér, hogy futtasd újra a poltura login parancsot. Ha az órád siet vagy késik, a szerver egy nonce értékkel válaszol, és a CLI újra elküldi a kérést azzal együtt. A Node-ban nincs olyan nem exportálható kulcstár, amelyet natív modul nélkül el lehetne érni, ezért a kulcsfájlt kezeld ugyanolyan körültekintéssel, mint a hitelesítő adatokat. Az API tokenek (POLTURA_TOKEN) nincsenek kulcshoz kötve. Kezeld őket titkos adatként.

Ha az API tanúsítványát egy olyan hitelesítésszolgáltató írta alá, amelyben a rendszered megbízik, de a Node nem (például egy vállalati proxy vagy a helyi fejlesztői CA), a CLI is megbízik benne. Az első kérés előtt hozzáadja a rendszer megbízható gyökértanúsítványait a Node sajátjaihoz. Ha egy kérésre nem érkezik válasz, a hibaüzenet elmagyarázza az okát: nem megbízható tanúsítvány, nem feloldható név, vagy elutasított, illetve megszakadt kapcsolat.

Kilépési kódok és újrapróbálkozásokHivatkozás másolása

A hitelesítő adat pontkeretének kimerülése miatt elutasított kérés sosem éri el a boltot, így a poltura theme parancsok addig várnak, ameddig az elutasítás jelzi (alkalmanként legfeljebb 30 másodpercet), és legfeljebb 8 alkalommal újra elküldik a kérést, mielőtt feladnák. A poltura store parancsok jelentik az elutasítást; a várakozási idő után futtasd őket újra. Lásd: rate limitek.

poltura app createHivatkozás másolása

Scaffold a new app project.

USAGE
  $ poltura app create [FLAGS] <dir>

ARGUMENTS
  dir                    Directory to create the project in (must be empty).

FLAGS
  --template <template>  Project template (choices: "hosted", "native", default:
                         "native").
  -h, --help             Show help.

A --template native csak UI worker fájlokat hoz létre. A --template hosted emellett létrehozza a src/server.ts fájlt is: egy /connect?installation=<installation id> route-ot, amely elindítja az OAuth folyamatot az adott telepítéshez, az /oauth/callback route-ot, amely befejezi azt és meghívja az App API-t, valamint egy termék webhookot. A README felsorolja a szerver által olvasott környezeti változókat. A létrehozott poltura.app.json nem tartalmaz appId-t, így a poltura app publish parancshoz szükséges a --app kapcsoló, amíg nem adsz hozzá egyet.

created hosted app in /home/dev/my-app

poltura appHivatkozás másolása

Create, build, validate and publish a Poltura app.

USAGE
  $ poltura app [FLAGS] COMMAND

COMMANDS
  create <dir>    Scaffold a new app project.
  build           Bundle workers and styles and write the release manifest.
  validate        Check the app config.
  dev             Rebuild on every change to the app sources.
  elements        List the storefront elements the app defines.
  publish         Build the app and upload it as a release for review.
  help [command]  Show help for a command.

FLAGS
  -h, --help      Show help.

EXAMPLES
  $ poltura app create my-app  Scaffold a native app.
  $ poltura app dev            Rebuild on every save.
  $ poltura app publish        Upload a release for review.

Build the app and upload it as a release for review.

USAGE
  $ poltura app publish [FLAGS]

FLAGS
  --api <url>           Gateway origin (POLTURA_API).
  --token <token>       Developer token, pltd_ or pltu_ (POLTURA_APP_TOKEN),
                        from Developer apps in admin.
  --app <appId>         App id; defaults to appId in poltura.app.json.
  --admin-origin <url>  Admin origin, to print the review link.
  --channel <channel>   Release channel (default: "production").
  -h, --help            Show help.

A poltura app build minden workers[].entry elemet IIFE JavaScriptté bundle-öl, a workers[].stylesheet fájlokat compile-olja Tailwinddel (minden stylesheet legfeljebb 262144 bájt lehet), ellenőrző kódokat (digest) ír, és az eredményt app manifestként értelmezi. A poltura app validate egy ideiglenes könyvtárba buildel, majd elemzi a manifest.json fájlt és a JSON extensions[] elemeket. A poltura app dev a src/ és a poltura.app.json változásakor újrabuildel, és kiírja: watch <digest>, amikor a manifest digestje megváltozik. A build és a dev a dist könyvtárba ír, hacsak nem adod meg a --out <dir> kapcsolót.

Egy kezelőfelület nélküli app, vagyis egy olyan integráció, amely csak az App API-t hívja és webhookokat fogad, nem deklarál workereket: UI runtime nélkül buildelhető és tehető közzé release-ként.

A workerek buildeléséhez a react, react-dom, tailwindcss és @poltura/app-ui csomagoknak elérhetőnek kell lenniük a projektben; először telepítsd a dependencyket. A build leáll a Install react in this project to build workers. üzenettel, ha ezek hiányoznak.

$ npm install

Buildelés és validálásHivatkozás másolása

A teljes példa, a Poltura Labs által készített Recommendations (lásd: Példák) felépítése a következő:

packages/app-sdk/examples/complete-app/
  poltura.app.json
  package.json
  src/server.ts
  src/elements.ts
  src/workers/admin-page.tsx
  src/workers/admin-product.tsx
  src/workers/storefront-product.tsx
  src/workers/storefront-footer.tsx
  src/workers/app-page.tsx
  src/styles.css
  src/locales/en.json
  src/locales/hu.json
  README.md

A szkriptjei ugyanazokat a lépéseket futtatják, amelyeket te is futtatsz a saját appodban:

pnpm test:unit
pnpm build
pnpm validate

built recommendations@1.0.0  sha256-qwcsxz+/Sn1wjxUbCKy7Ah/ROvTpZrZMf/8OTBIGg9Q=  5 workers

built recommendations@1.0.0  sha256-qwcsxz+/Sn1wjxUbCKy7Ah/ROvTpZrZMf/8OTBIGg9Q=  5 workers
ok recommendations@1.0.0
  manifest.json  7765 bytes

KözzétételHivatkozás másolása

A poltura app publish buildeli az appot, és feltölti release-ként felülvizsgálatra. A release-t elküldi a --api kapcsolóban (vagy a POLTURA_API változóban) megadott Poltura API-nak, és kiírja: published <releaseId>. A --admin-origin kapcsoló megadásakor a felülvizsgálati linket is kiírja.

poltura app publish --api "$POLTURA_API" --app <app id> --token "$POLTURA_APP_TOKEN"

A --api a Poltura API alapcíme. Alapértelmezése a https://api.poltura.com; csak akkor add meg, vagy állítsd be a POLTURA_API változót, ha másik környezetet használsz. A --app az app azonosítója a Fejlesztői alkalmazások felületről. Alternatívaként a poltura.app.json fájl appId mezőjéből is származhat, de a sablon nem hoz létre ilyet. Add meg a --channel kapcsolót, ha a production csatornától eltérő release-csatornát szeretnél választani.

A development csatornán lévő release-eket a kereskedők nem tudják telepíteni (release_not_production). Felülvizsgálat és telepítés: Közzététel, felülvizsgálat, telepítés.

Ellenőrzés a közzététel előttHivatkozás másolása

A poltura check [dir] az egyetlen parancs, amelyet közzététel előtt futtatnod kell. Néhány másodperc alatt, hálózati kapcsolat nélkül adja meg ugyanazt az eredményt, mint a Poltura felülvizsgálata. Megállapítja, hogy a könyvtár app-e (tartalmazza a poltura.app.json fájlt) vagy téma (tartalmazza a theme.json fájlt), és lefuttatja a releváns ellenőrzéseket:

A kódszabályok biztosítják, hogy a kívülről érkező adatok elemezve és típusozva maradjanak: nincsenek unknown paraméterek vagy visszatérési típusok, nincsenek unknown, any vagy object szótárak, minden típuskényszerítésen szerepel egy // SAFETY: megjegyzés, és nincs runtime typeof ellenőrzés elemezetlen értékeken. Elemezd az értéket egy sémával ott, ahol belép a kódodba, és a típusos eredményt add tovább.

Az ember által olvasható kimenet fájlonként van csoportosítva; minden találat tartalmazza az azt kiváltó szabályt és egy fix: sort, amely leírja, mit kell változtatni.

poltura.app.json
  ✖ /permissions/required/2/id "orders.reed" is not a permission id. [permissions/unknown]
    fix: Did you mean "orders.read" or "orders.refund"? The full list is at https://developers.poltura.com/apps/permissions.

src/orders.ts
  ✖ 2:7 A `typeof` check narrows a representation without establishing its contract. Parse input at its I/O boundary, then branch on the domain value. [anti-slop/no-runtime-typeof]
    fix: Parse the value with a schema at the boundary, then branch on the parsed value.

skipped build: fix the manifest first
✖ failed: 2 errors, 0 warnings (app, 1.4s)

A --json kapcsolóval a jelentés a következő formátumú:

{
  "v": 1,
  "kind": "app",
  "root": "/work/my-app",
  "ok": false,
  "totals": { "error": 2, "warning": 0, "info": 0 },
  "findings": [
    {
      "severity": "error",
      "rule": "permissions/unknown",
      "message": "\"orders.reed\" is not a permission id.",
      "hint": "Did you mean \"orders.read\" or \"orders.refund\"? ...",
      "file": "poltura.app.json",
      "pointer": "/permissions/required/2/id"
    }
  ],
  "steps": [{ "id": "manifest", "ran": true }, { "id": "agent", "ran": false, "note": "the app declares no src/agent entry" }],
  "fixed": 0,
  "durationMs": 1432
}

A severity értéke error, warning vagy info. Egy találat tartalmazza a file mezőt (a projekthez viszonyított relatív útvonallal), valamint ahol elérhető, a line, column és pointer adatokat. A rule stabil, így lehet illeszteni rá: manifest/*, permissions/*, build/failed, agent/*, theme/*, vagy egy kódszabály neve, mint például az anti-slop/no-runtime-typeof. Kilépési kódok: 0, ha nincsenek hibák (és --strict esetén figyelmeztetések sincsenek), 1, ha hibát talált, 2, ha a könyvtár nem app és nem is téma.

A poltura check csak a src/agent belépési pont beolvasásához futtatja az app saját kódját; hálózati hívást nem indít. Futtasd a CI-ben a poltura check --json --strict paranccsal, valamint minden poltura app publish előtt.

TémákHivatkozás másolása

A témákkal kapcsolatos parancsoknak – beleértve a poltura theme check parancsot is – saját oldaluk van: Témaparancsok.

Következő lépésekHivatkozás másolása

• Átadás a kereskedőknek: mi történik a publish után.
• Témaparancsok, Boltparancsok és API tokenek.
• Jogosultságok és témakörök: a generált referencia-táblázatok.