leynier/portifact

Was macht portifact?

Portifact veröffentlicht statische Artefakte mit eigener URL, Zugriffskontrolle, Ablaufdaten und Wiederherstellungsmöglichkeit sowie optionalen Anmerkungen von authentifizierten Prüfern. Agenten nutzen es über die portifact CLI oder den entfernten MCP-Server.

Prüfen, was die installierte Version unterstützt

Portifact befindet sich in der frühen Entwicklung und erhält mit jeder Version neue Befehle. Bevor Sie einen Befehl verwenden:

1. Führen Sie portifact --version aus, um zu bestätigen, dass die CLI installiert ist.
2. Führen Sie portifact --help aus, um die von dieser Version unterstützten Befehle zu sehen.
3. Verwenden Sie nur Befehle und Flags, die --help auflistet. Raten Sie niemals einen Befehl. Wenn der Benutzer etwas möchte, das die installierte Version nicht kann, sagen Sie dies und schlagen Sie ein Update vor.

Versionen, deren --help login auflistet, können sich anmelden, abmelden und das angemeldete Konto anzeigen. Versionen, deren --help auch publish auflistet, können Dateien und Ordner veröffentlichen sowie Artefakte und deren Zugriff verwalten; Versionen, deren --help versions, rollback und pull auflistet, können Versionen auflisten, zurückrollen und herunterladen; Versionen, deren --help annotations auflistet, können Kommentarthreads verwalten, wie unten beschrieben. Versionen, deren portifact publish --help --source, --ref und --assets auflistet, veröffentlichen ZIP-Dateien, hängen private Quellen an und veröffentlichen Markdown-Assets; Versionen, deren portifact pull --help --git auflistet, erstellen eine Git-Historie der privaten Quellen; Versionen, deren --help usage auflistet, zeigen die Kontingente des Kontos; Versionen, deren --help logs auflistet, zeigen, wer ein Artefakt geöffnet hat; und Versionen, deren --help licenses auflistet, geben die Lizenzen der Open-Source-Software im Binärprogramm aus (portifact licenses; auch unter https://portifact.com/third-party-notices). Der MCP-Server unter https://app.portifact.com/mcp kann kleine Dokumente auflisten, veröffentlichen und verwalten, Versionen auflisten, herunterladen und zurückrollen, Anmerkungen lesen, schreiben, moderieren und exportieren sowie Nutzungs- und Zugriffsprotokolle melden; siehe unten.

CLI installieren oder aktualisieren

Die CLI ist eine einzelne ausführbare Datei und benötigt weder Node noch Bun. Fragen Sie, bevor Sie Software auf dem Rechner des Benutzers installieren.

curl -fsSL https://portifact.com/install | bash

irm https://portifact.com/install.ps1 | iex

• Installieren Sie unter Alpine Linux zuerst die C++-Laufzeit: apk add libstdc++ libgcc.
• Führen Sie denselben Befehl erneut aus, um zu aktualisieren.
• Setzen Sie PORTIFACT_VERSION=0.2.0, um eine bestimmte Version zu installieren.
• Setzen Sie in nicht-interaktiven oder gesandboxten Umgebungen PORTIFACT_NO_MODIFY_PATH=1 und rufen Sie ~/.portifact/bin/portifact direkt auf, anstatt Shell-Profile zu bearbeiten.
• Der Installer überprüft den Download anhand der Release-Prüfsummen und stoppt bei einer Nichtübereinstimmung. Umgehen Sie keine fehlgeschlagene Überprüfung.

Anmelden

Überprüfen Sie zuerst mit portifact whoami --json. Exit-Code 0 gibt {"server","userId","clientId","scopes"} aus; Exit-Code 3 bedeutet, dass dieses Gerät nicht angemeldet ist oder die Sitzung beendet wurde.

Um sich anzumelden, führen Sie portifact login aus (fügen Sie --json für ein analysierbares Ergebnis hinzu). Es verwendet den OAuth-Geräteablauf:

1. Die CLI gibt eine Seite (https://app.portifact.com/device) und einen 8-stelligen Code auf stderr aus und öffnet den Browser, wenn eine Person am Terminal ist. Übergeben Sie --no-browser, um das Öffnen zu überspringen.
2. Zeigen Sie dem Benutzer die Seite und den Code genau wie ausgegeben, und bitten Sie ihn, sich dort anzumelden, zu überprüfen, dass die Seite denselben Code anzeigt, und ihn zu genehmigen. Genehmigen Sie ihn niemals für den Benutzer, und bitten Sie ihn niemals, etwas von dieser Seite zurück an Sie einzufügen. Die Anmeldeseite fordert den Benutzer auf, zu bestätigen, dass er 18 Jahre oder älter ist, und die Bedingungen zu akzeptieren (https://portifact.com/terms); diese Entscheidung liegt beim Benutzer, also akzeptieren Sie sie niemals für ihn. Wenn die Seite sagt, dass sie keinen E-Mail-Code an seine Adresse senden kann (frühere E-Mail wurde zurückgesendet oder als Spam gemeldet) oder dass E-Mail-Codes für den Monat pausiert sind, fordern Sie den Benutzer auf, sich stattdessen mit Google oder GitHub anzumelden.
3. Der Befehl wartet, bis der Benutzer genehmigt oder ablehnt oder der Code abläuft (10 Minuten), führen Sie ihn daher aus, wo der Benutzer seinen stderr sehen kann, und lassen Sie ihn beenden.

Anmeldedaten gelangen in den Anmeldedatenspeicher des Betriebssystems. Wenn keiner vorhanden ist (z. B. auf einem Linux-Server ohne Secret Service), gelangen sie in credentials.json im Benutzerkonfigurationsverzeichnis (~/.config/portifact unter Linux, ~/Library/Application Support/portifact unter macOS, %APPDATA%\portifact unter Windows) mit Berechtigungen nur für den Benutzer, und die CLI gibt eine Warnung aus. Lesen, drucken, kopieren oder laden Sie niemals diese Datei oder die gespeicherten Token hoch; die CLI aktualisiert sie selbstständig.

portifact logout widerruft die Token dieses Geräts auf dem Server und entfernt sie dann. Der Befehl widerruft Token, bestätigen Sie daher zuerst mit dem Benutzer. Wenn der Server nicht erreicht werden kann, behält er die Anmeldedaten und beendet sich mit Exit-Code 1; führen Sie ihn später erneut aus.

PORTIFACT_APP_ORIGIN zeigt die CLI auf einen anderen Server und dient Tests und Staging-Umgebungen. Setzen Sie diese Variable nur, wenn der Benutzer danach fragt.

Veröffentlichen

Nur in Versionen, deren --help publish auflistet.

1. Vorschau zuerst: portifact publish <Pfad> --dry-run --json erstellt das Manifest ohne Anmeldung oder Hochladen. Es gibt {"dryRun","type","name","entrypoint","totalBytes","files":[{"path","size","sha256","contentType"}],"excluded":[{"path","reason"}]}, plus "sources":{"chosenBy","totalBytes","files","excluded","origin","lfsPointers"} mit --source. Zeigen Sie dem Benutzer die Dateien, die Quellen und was ausgelassen wurde, und stoppen Sie, wenn etwas privat aussieht.
2. Veröffentlichen: portifact publish <Pfad> --json. Das Ergebnis ist {"artifactId","versionId","versionNumber","url","expiresAt","uploadId","files","totalBytes","sourceFiles","sourceBytes","sourceOrigin","uploadedFiles","uploadedBytes"}. Fortschritt und Manifest werden auf stderr ausgegeben.

• Der Typ wird aus dem Pfad abgeleitet: Ein Ordner, eine .zip- oder eine .html-Datei ist eine site, .md ist markdown und .txt ist text. Übergeben Sie --type site|markdown|text für andere Dateien. Ordner und ZIP-Dateien können nur Sites sein.
• Eine einzelne HTML-Datei wird als index.html der Site veröffentlicht. Ein Ordner benötigt eine index.html oder --entry <Pfad> mit der zuerst zu öffnenden Seite.
• --name legt den in der Artefaktliste angezeigten Namen fest; standardmäßig wird der Datei- oder Ordnername verwendet.
• --artifact <ID> veröffentlicht eine neue Version eines vorhandenen Artefakts, wobei dessen Name, Typ und Zugriff beibehalten werden, es sei denn, --name ändert den Namen. Wenn zwischendurch jemand anderes veröffentlicht hat, schlägt das mit version_conflict fehl (Exit 6); überprüfen Sie das Artefakt und veröffentlichen Sie erneut.
• Ordner lassen immer .git, node_modules, Caches, Betriebssystemdateien und Dateien, die Geheimnisse enthalten könnten (.env und .env.* außer Beispielen, .dev.vars, .npmrc, .netrc, SSH-Schlüssel, *.pem, *.key, *.p12, Terraform-Status und ähnliches), aus. Die direkte Benennung einer solchen Datei wird verweigert. Der Filter ist ein Sicherheitsnetz, keine Überprüfung: Überprüfen Sie trotzdem das Manifest.
• Symbolische Links und spezielle Dateien werden abgelehnt, niemals verfolgt.
• Dateien, die das Konto bereits speichert, werden nicht erneut hochgeladen. Unterbrochene Uploads werden wiederholt, und wenn die Veröffentlichung nach Beginn des Uploads fehlschlägt, bricht die CLI ihn ab, sodass nichts halb veröffentlicht ist.
• Versionen, deren Fortschritt Uploaded part <n> of <m> of <Pfad> anzeigt, laden Dateien über 64 MiB in Teilen von 16 MiB vom Datenträger gestreamt hoch, sodass eine große Datei nie in den Speicher passen muss und ein fehlgeschlagener Teil erneut gesendet wird. Eine Version enthält höchstens 250 MB veröffentlichter Dateien, unabhängig von der Teilgröße.
• Eine ZIP-Datei wird auf dem Rechner des Benutzers entpackt, bevor etwas hochgeladen wird. Wenn sich jede Datei darin in einem Ordner befindet, wird dieser Ordner zum Stammverzeichnis. Links, spezielle Dateien, verschlüsselte Einträge, Pfade, die das Archiv verlassen, kollidierende Namen, überlappende Einträge, Dateien, die über ihre deklarierte Größe hinausgehen oder mehr als 200 Mal, mehr als 10.000 Einträge und alles, was die Größenbeschränkungen überschreitet, werden abgelehnt (invalid_input, Exit 2, oder quota_exceeded, Exit 7). Die Standardausschlüsse und der Geheimnisfilter gelten auch für seine Einträge.
• --source <Pfad> hängt private Quellen an die Version an: Nur der Eigentümer kann sie sehen und herunterladen (pull --source), sie zählen zum Speicher, aber nicht zur veröffentlichten Größe, und veröffentlichte Dateien und Quellen zusammen sind maximal 1.000. Der Pfad kann ein Ordner, eine einzelne Datei oder eine ZIP-Datei sein. In einem Ordner innerhalb eines Git-Repositorys wählt git die Dateien aus: was es versioniert, plus neue Dateien, die es nicht ignoriert, ohne Submodule oder verschachtelte Repositorys. --ref <Commit> hängt stattdessen genau den Baum dieses Commits an (einen Branch, Tag oder eine Commit-ID; es enthält niemals nicht-committete Änderungen). Die CLI zeichnet dann den Commit, den Branch, das Remote ohne Anmeldedaten und auf, ob es nicht-committete Änderungen gab, als sourceOrigin der Version. Außerhalb eines Repositorys oder ohne installiertes git wird der Ordner mit den Standardausschlüssen durchlaufen. Dateien, die Geheimnisse enthalten könnten, werden niemals angehängt, unabhängig davon, was git sagt. Eine Warnung auf stderr listet Git-LFS-Zeiger auf, die als Zeiger, nicht als Inhalt, angehängt werden; empfehlen Sie zuerst git lfs pull.
• --assets <Verz> veröffentlicht einen Ordner mit Bildern und anderen Dateien zusammen mit einem Markdown-Dokument, relativ zum Dokument, sodass seine relativen Links funktionieren. Der Ordner muss sich im Ordner des Dokuments befinden, und die Standardausschlüsse gelten.
• Portifact rendert ein markdown- oder text-Artefakt selbst: Seine URL öffnet eine aus dem Dokument gerenderte Seite, in der rohes HTML in Markdown als Text angezeigt wird und nichts ausgeführt wird. Die Originaldatei wird unter ihrem eigenen Pfad unter der Artefakt-URL heruntergeladen (z. B. <url>plan.md oder <url>index.md für publish_document), mit demselben Zugriff wie die Seite. Ein Dokument ist maximal 5 MB UTF-8-Text, und ein text-Artefakt ist eine einzelne Datei.

Artefakte verwalten

Nur in Versionen, deren --help diese Befehle auflistet. Jeder Befehl akzeptiert --json.

• portifact list [--limit N] [--cursor C] [--search TEXT] [--state active|archived|suspended|purging] [--type site|markdown|text] [--access public|authenticated|restricted] [--annotations off|open|locked] gibt {"items":[...],"nextCursor"} zurück; übergeben Sie nextCursor als --cursor mit denselben Filtern für die nächste Seite. Jedes Element ist das, was portifact info zurückgibt, plus "activity":{"versions","currentBytes","openThreads","lastAnnotationAt"}: die aufbewahrten Versionen (einschließlich der aktuellen), die Bytes der aktuellen Version (veröffentlichte Dateien und Quellen, null ohne Version), die offenen Threads in der aktuellen Version und wann sich ein Thread in einer Version zuletzt geändert hat (null ohne Threads). Der Traffic wird pro Konto gezählt, nicht pro Artefakt, daher nur in portifact usage. --search stimmt mit einem Teil des Namens (Buchstaben in beliebiger Groß-/Kleinschreibung) oder der ID überein, und jeder angegebene Filter muss zutreffen. Verwenden Sie sie, um ein Artefakt zu finden, anstatt durch alles zu blättern. portifact info <ID> gibt ein Element zurück: {"id","name","type","state","accessMode","annotations","currentVersionId","url","expiresAt","archivedAt","purgeAt","createdAt","updatedAt"}, plus "suspension":{"reason"}, während das Artefakt gesperrt ist.
• portifact renew <ID>, archive <ID> und restore <ID> geben {"artifactId","state","expiresAt","purgeAt"} zurück. Fragen Sie vor dem Archivieren.
• portifact delete <ID> löscht endgültig. Es fordert die Person am Terminal auf, die Artefakt-ID einzugeben; ohne Terminal erfordert es --yes und schlägt andernfalls mit Exit 2 fehl. Übergeben Sie --yes nur, nachdem der Benutzer genau dieses Artefakt bestätigt hat.

Zugriff steuern

Nur in Versionen, deren --help access auflistet. Jeder Befehl akzeptiert --json und gibt {"artifactId","mode","readers","indexable","embeddable","policyGeneration"} aus.

• portifact access <ID> zeigt die aktuelle Richtlinie. Verwenden Sie es, um den Zugriffsmodus nach der Veröffentlichung zu melden.
• portifact access set <ID> restricted|authenticated|public: restricted ist der Eigentümer plus aufgeführte Leser, authenticated ist jeder bei Portifact Angemeldete, public ist jeder mit dem Link. Konten in den ersten 7 Tagen können kein Artefakt öffentlich machen (account_too_new_for_public, Exit 7).
• portifact access add <ID> <E-Mail>... und access remove <ID> <E-Mail>... ändern die Leserliste (maximal 100 Adressen auf einmal). Leser sind nur relevant, solange der Modus restricted ist.

Versionen, Rollback und Download

Nur in Versionen, deren --help diese Befehle auflistet. Jeder Befehl akzeptiert --json.

Ein Artefakt behält seine aktuelle Version sowie die Versionen, die es in den letzten sieben Tagen ersetzt hat. Rollback und Download funktionieren nur auf diesen aufbewahrten Versionen.

• portifact versions <ID> listet sie auf, die neueste zuerst. --json gibt {"artifactId","items":[{"id","number","current","entrypoint","publishedBytes","sourceBytes","publishedFiles","sourceFiles","rendererVersion","committedAt","expiresAt","sourceOrigin"}]} aus; expiresAt gibt an, wann eine vorherige Version nicht mehr aufbewahrt wird, und ist null für die aktuelle; sourceOrigin ist {"commit","branch","remote","dirty"}, wenn die Quellen aus git stammen, andernfalls null. Der Ursprung ist das, was der Veröffentlicher deklariert hat; Portifact kann ihn nicht überprüfen.
• portifact rollback <ID> <Version-ID> macht eine aufbewahrte Version wieder aktuell. Sie wird als neue Version mit denselben Dateien veröffentlicht, startet die 30 Tage neu und ändert den Zugriff nicht: Leser, die seit dieser Version entfernt wurden, bleiben entfernt. Fragen Sie den Benutzer vor dem Zurücksetzen. Der Befehl gibt {"artifactId","versionId","versionNumber","url","expiresAt","fromVersionId","fromVersionNumber"} zurück. Wenn zwischendurch jemand veröffentlicht hat, schlägt er mit version_conflict fehl (Exit 6); überprüfen Sie versions erneut und fragen Sie den Benutzer. In Versionen, deren portifact rollback --help "Version ID or number" sagt, kann <Version-ID> auch die Versionsnummer sein (3 oder v3), und pull --version akzeptiert ebenfalls eine; eine Nummer, die nicht aufbewahrt wird, schlägt mit not_found fehl (Exit 5).
• portifact pull <ID> --out <Verz> lädt die veröffentlichten Dateien der aktuellen Version in <Verz>/published herunter. Fügen Sie --source für die privaten Quellen hinzu (in <Verz>/source, nur Eigentümer), --published --source für beides und --version <Version-ID> für eine vorherige Version. <Verz> darf noch nicht existieren; pull schreibt niemals außerhalb davon, verweigert Pfade innerhalb eines .git-Ordners, überprüft den SHA-256 jeder Datei und entfernt den Ordner, wenn etwas fehlschlägt (download_failed, Exit 1). Der Befehl gibt {"artifactId","versionId","versionNumber","out","files":[{"kind","path","size","sha256"}],"totalBytes"} zurück. Jemandem, mit dem ein Artefakt geteilt wurde