@privos_ai/app-server 0.8.4 → 0.9.0

package/dist/cli/lib/portal-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Thin fetch wrapper for the `/api/cloud/marketplace/*` publish routes: JSON
+ * request/response, retry-after-driven backoff on transient 429/5xx, and a
+ * typed {@link PortalError} carrying the Portal's `code` for callers that
+ * branch on specific wire-contract error codes (`VERSION_SEMVER_EXISTS`,
+ * `PUBLISH_GRANT_EXPIRED`, `PUBLISH_GRANT_MISMATCH`, `LISTING_NOT_BOUND`,
+ * `LISTING_UNRESOLVED`, RFC 8628 `slow_down`, …).
+ */
+export declare class PortalError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, status: number, code?: string | undefined, retryAfterMs?: number | undefined);
+}
+export type PortalRequestInit = Readonly<{
+    method?: string;
+    /** Bearer token: publisher token (`pvp_…`), publish grant (`pvg_…`), or none (anonymous create). */
+    token?: string;
+    body?: unknown;
+}>;
+export type PortalClientOptions = Readonly<{
+    origin: string;
+    basePath?: string;
+    fetchImpl?: typeof fetch;
+    maxRetries?: number;
+    sleepImpl?: (ms: number) => Promise<void>;
+}>;
+export declare function parseRetryAfterMs(header: string | null): number | undefined;
+export declare class PortalClient {
+    private readonly origin;
+    private readonly basePath;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly sleepImpl;
+    constructor(options: PortalClientOptions);
+    request<T>(path: string, init?: PortalRequestInit): Promise<T>;
+}
+//# sourceMappingURL=portal-client.d.ts.map

package/dist/cli/lib/portal-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal-client.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/portal-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGpB,MAAM,EAAE,MAAM;aACd,IAAI,CAAC,EAAE,MAAM;aACb,YAAY,CAAC,EAAE,MAAM;gBAHrC,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,YAAY,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CACf,CAAC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C,CAAC,CAAC;AASH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAM3E;AAED,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;gBAE9C,OAAO,EAAE,mBAAmB;IAQlC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,CAAC,CAAC;CAoCxE"}

package/dist/cli/lib/portal-client.js

@@ -0,0 +1,87 @@
+/**
+ * Thin fetch wrapper for the `/api/cloud/marketplace/*` publish routes: JSON
+ * request/response, retry-after-driven backoff on transient 429/5xx, and a
+ * typed {@link PortalError} carrying the Portal's `code` for callers that
+ * branch on specific wire-contract error codes (`VERSION_SEMVER_EXISTS`,
+ * `PUBLISH_GRANT_EXPIRED`, `PUBLISH_GRANT_MISMATCH`, `LISTING_NOT_BOUND`,
+ * `LISTING_UNRESOLVED`, RFC 8628 `slow_down`, …).
+ */
+export class PortalError extends Error {
+    status;
+    code;
+    retryAfterMs;
+    constructor(message, status, code, retryAfterMs) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'PortalError';
+    }
+}
+const DEFAULT_BASE_PATH = '/api/cloud/marketplace';
+const DEFAULT_MAX_RETRIES = 5;
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function parseRetryAfterMs(header) {
+    if (!header)
+        return undefined;
+    if (/^\d+$/.test(header))
+        return Number(header) * 1000;
+    const parsed = Date.parse(header);
+    if (Number.isNaN(parsed))
+        return undefined;
+    return Math.max(0, parsed - Date.now());
+}
+export class PortalClient {
+    origin;
+    basePath;
+    fetchImpl;
+    maxRetries;
+    sleepImpl;
+    constructor(options) {
+        this.origin = options.origin.replace(/\/+$/, '');
+        this.basePath = options.basePath ?? DEFAULT_BASE_PATH;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.sleepImpl = options.sleepImpl ?? defaultSleep;
+    }
+    async request(path, init = {}) {
+        const method = init.method ?? 'GET';
+        const url = `${this.origin}${this.basePath}${path}`;
+        let attempt = 0;
+        for (;;) {
+            const response = await this.fetchImpl(url, {
+                method,
+                headers: {
+                    ...(init.token ? { Authorization: `Bearer ${init.token}` } : {}),
+                    ...(init.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                },
+                body: init.body === undefined ? undefined : JSON.stringify(init.body),
+            });
+            const text = await response.text();
+            let parsed;
+            try {
+                parsed = text ? JSON.parse(text) : {};
+            }
+            catch {
+                parsed = { raw: text.slice(0, 500) };
+            }
+            if (response.ok)
+                return parsed;
+            const record = parsed;
+            const code = typeof record?.code === 'string' ? record.code : undefined;
+            const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'));
+            const transient = response.status === 429 || (response.status >= 500 && response.status < 600);
+            if (transient && attempt < this.maxRetries) {
+                const backoffMs = retryAfterMs ?? Math.min(30_000, 1_000 * 2 ** attempt);
+                await this.sleepImpl(backoffMs);
+                attempt += 1;
+                continue;
+            }
+            const message = typeof record?.message === 'string' ? record.message : `${method} ${path} failed (${response.status})`;
+            throw new PortalError(message, response.status, code, retryAfterMs);
+        }
+    }
+}
+//# sourceMappingURL=portal-client.js.map

package/dist/cli/lib/portal-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal-client.js","sourceRoot":"","sources":["../../../src/cli/lib/portal-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGpB;IACA;IACA;IAJjB,YACC,OAAe,EACC,MAAc,EACd,IAAa,EACb,YAAqB;QAErC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAS;QACb,iBAAY,GAAZ,YAAY,CAAS;QAGrC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC3B,CAAC;CACD;AAiBD,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AACnD,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B,SAAS,YAAY,CAAC,EAAU;IAC/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAqB;IACtD,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,OAAO,YAAY;IACP,MAAM,CAAS;IACf,QAAQ,CAAS;IACjB,SAAS,CAAe;IACxB,UAAU,CAAS;IACnB,SAAS,CAAgC;IAE1D,YAAY,OAA4B;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;QACtD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAC5C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAC5D,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,YAAY,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,IAAY,EAAE,OAA0B,EAAE;QAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;QACpC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC;QACpD,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,SAAS,CAAC;YACT,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;gBAC1C,MAAM;gBACN,OAAO,EAAE;oBACR,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChE,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;iBAC1E;gBACD,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;aACrE,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACJ,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACR,MAAM,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YACtC,CAAC;YACD,IAAI,QAAQ,CAAC,EAAE;gBAAE,OAAO,MAAW,CAAC;YAEpC,MAAM,MAAM,GAAG,MAA6C,CAAC;YAC7D,MAAM,IAAI,GAAG,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YACxE,MAAM,YAAY,GAAG,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;YAC5E,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;YAC/F,IAAI,SAAS,IAAI,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC5C,MAAM,SAAS,GAAG,YAAY,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;gBACzE,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;gBAChC,OAAO,IAAI,CAAC,CAAC;gBACb,SAAS;YACV,CAAC;YACD,MAAM,OAAO,GAAG,OAAO,MAAM,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,YAAY,QAAQ,CAAC,MAAM,GAAG,CAAC;YACvH,MAAM,IAAI,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;QACrE,CAAC;IACF,CAAC;CACD"}

package/dist/cli/lib/upload.d.ts

@@ -0,0 +1,54 @@
+import { PortalClient } from './portal-client.js';
+/** Portal's `express.json()` body limit is 10 MB; base64 inflates bytes ~1.37x, so 5 MB parts stay well under it. */
+export declare const DEFAULT_PART_SIZE_BYTES: number;
+export type UploadSession = Readonly<{
+    uploadId: string;
+}>;
+export declare function createUploadSession(client: PortalClient, token: string, listingId: string, request: Readonly<{
+    fileName: string;
+    totalBytes: number;
+    paths: readonly string[];
+}>): Promise<UploadSession>;
+/**
+ * Uploads `buffer` as base64 parts, one at a time (sequential — never
+ * concurrent), retrying transient 5xx/429 per-part via {@link PortalClient}'s
+ * own retry-after backoff.
+ */
+export declare function uploadPartsSequentially(client: PortalClient, token: string, uploadId: string, buffer: Buffer, partSizeBytes?: number, onProgress?: (part: number, totalParts: number) => void): Promise<number>;
+export type CompleteUploadResult = Readonly<{
+    sha256: string;
+    uploadId: string;
+    manifestDigest: string;
+    manifest: Record<string, unknown>;
+}>;
+export declare function completeUpload(client: PortalClient, token: string, uploadId: string): Promise<CompleteUploadResult>;
+export type CreatedVersion = Readonly<{
+    id: string;
+    semver: string;
+    state: string;
+}>;
+export declare function createVersion(client: PortalClient, token: string, listingId: string, request: Readonly<{
+    semver: string;
+    uploadId: string;
+    changelog: string;
+}>): Promise<CreatedVersion>;
+export declare function submitVersion(client: PortalClient, token: string, listingId: string, versionId: string): Promise<void>;
+export type ListingVersion = Readonly<{
+    id: string;
+    semver: string;
+    state: string;
+}> & Record<string, unknown>;
+export type ListingDetail = Readonly<{
+    listing: Record<string, unknown>;
+    versions: readonly ListingVersion[];
+    events?: readonly Record<string, unknown>[];
+}>;
+export declare function getListingDetail(client: PortalClient, token: string, listingId: string): Promise<ListingDetail>;
+export type WaitForPreflightOptions = Readonly<{
+    timeoutMs?: number;
+    pollMs?: number;
+    sleepImpl?: (ms: number) => Promise<void>;
+}>;
+/** Polls listing detail up to `timeoutMs` (default 60 s) while the version sits in `PREFLIGHT_PENDING`. */
+export declare function waitForPreflight(client: PortalClient, token: string, listingId: string, versionId: string, options?: WaitForPreflightOptions): Promise<ListingVersion | undefined>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/cli/lib/upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/upload.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/upload.js

@@ -0,0 +1,75 @@
+/** Portal's `express.json()` body limit is 10 MB; base64 inflates bytes ~1.37x, so 5 MB parts stay well under it. */
+export const DEFAULT_PART_SIZE_BYTES = 5 * 1024 * 1024;
+export async function createUploadSession(client, token, listingId, request) {
+    const response = await client.request(`/creator/listings/${listingId}/uploads`, {
+        method: 'POST',
+        token,
+        body: {
+            fileName: request.fileName,
+            totalBytes: request.totalBytes,
+            kind: 'APP_SOURCE',
+            paths: request.paths,
+        },
+    });
+    const upload = response.upload;
+    const uploadId = upload?.id;
+    if (typeof uploadId !== 'string' || !uploadId)
+        throw new Error('Portal did not return an upload session id.');
+    return { uploadId };
+}
+/**
+ * Uploads `buffer` as base64 parts, one at a time (sequential — never
+ * concurrent), retrying transient 5xx/429 per-part via {@link PortalClient}'s
+ * own retry-after backoff.
+ */
+export async function uploadPartsSequentially(client, token, uploadId, buffer, partSizeBytes = DEFAULT_PART_SIZE_BYTES, onProgress) {
+    const totalParts = Math.max(1, Math.ceil(buffer.length / partSizeBytes));
+    for (let index = 0; index < totalParts; index += 1) {
+        const start = index * partSizeBytes;
+        const end = Math.min(buffer.length, start + partSizeBytes);
+        const chunk = buffer.subarray(start, end);
+        await client.request(`/creator/uploads/${uploadId}/parts/${index + 1}`, {
+            method: 'PUT',
+            token,
+            body: { dataBase64: chunk.toString('base64') },
+        });
+        onProgress?.(index + 1, totalParts);
+    }
+    return totalParts;
+}
+export async function completeUpload(client, token, uploadId) {
+    const response = await client.request(`/creator/uploads/${uploadId}/complete`, { method: 'POST', token, body: {} });
+    return {
+        sha256: String(response.sha256),
+        uploadId: String(response.uploadId ?? uploadId),
+        manifestDigest: String(response.manifestDigest),
+        manifest: response.manifest ?? {},
+    };
+}
+export async function createVersion(client, token, listingId, request) {
+    const response = await client.request(`/creator/listings/${listingId}/versions`, { method: 'POST', token, body: request });
+    const version = response.version;
+    return { id: String(version.id), semver: String(version.semver), state: String(version.state) };
+}
+export async function submitVersion(client, token, listingId, versionId) {
+    await client.request(`/creator/listings/${listingId}/submit`, { method: 'POST', token, body: { versionId } });
+}
+export async function getListingDetail(client, token, listingId) {
+    return client.request(`/creator/listings/${listingId}`, { method: 'GET', token });
+}
+/** Polls listing detail up to `timeoutMs` (default 60 s) while the version sits in `PREFLIGHT_PENDING`. */
+export async function waitForPreflight(client, token, listingId, versionId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    const pollMs = options.pollMs ?? 1_000;
+    const sleepImpl = options.sleepImpl ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = Date.now() + timeoutMs;
+    let detail = await getListingDetail(client, token, listingId);
+    let version = detail.versions.find((item) => item.id === versionId);
+    while (version?.state === 'PREFLIGHT_PENDING' && Date.now() < deadline) {
+        await sleepImpl(pollMs);
+        detail = await getListingDetail(client, token, listingId);
+        version = detail.versions.find((item) => item.id === versionId);
+    }
+    return version;
+}
+//# sourceMappingURL=upload.js.map

package/dist/cli/lib/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../src/cli/lib/upload.ts"],"names":[],"mappings":"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"}

package/dist/manifest-lint-cli.js

@@ -1,18 +1,7 @@
 #!/usr/bin/env node
-import fs from 'node:fs';
-import path from 'node:path';
-import { lintManifest } from './manifest-tools.js';
-const manifestPath = path.resolve(process.argv[2] || 'privos-app.json');
-let manifest;
-try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-}
-catch {
-    console.error(JSON.stringify({ valid: false, errors: [`Unable to read valid JSON from ${manifestPath}`] }, null, 2));
-    process.exit(1);
-}
-const result = lintManifest(manifest);
-console.log(JSON.stringify({ manifestPath, ...result }, null, 2));
-if (!result.valid)
-    process.exit(1);
+// Compatibility alias for `privos-app lint`: kept as its own bin entry
+// (`privos-app-lint`) with byte-identical output and exit code, delegating
+// to the same implementation so the two can never drift.
+import { runLint } from './cli/commands/lint.js';
+process.exit(runLint(process.argv.slice(2)));
 //# sourceMappingURL=manifest-lint-cli.js.map

package/dist/manifest-lint-cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-lint-cli.js","sourceRoot":"","sources":["../src/manifest-lint-cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC;AACxE,IAAI,QAAiB,CAAC;AACtB,IAAI,CAAC;IACJ,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC;AAAC,MAAM,CAAC;IACR,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,kCAAkC,YAAY,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACrH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC;AAED,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;AACtC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAClE,IAAI,CAAC,MAAM,CAAC,KAAK;IAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"manifest-lint-cli.js","sourceRoot":"","sources":["../src/manifest-lint-cli.ts"],"names":[],"mappings":";AACA,uEAAuE;AACvE,2EAA2E;AAC3E,yDAAyD;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@privos_ai/app-server",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Business-agnostic PrivOS MCP App server runtime — Direct HTTP + Relay WebSocket",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
+    "privos-app": "./dist/cli/index.js",
     "privos-app-lint": "./dist/manifest-lint-cli.js"
   },
   "exports": {
@@ -40,6 +41,7 @@
   },
   "files": [
     "dist",
+    "skill",
     "README.md",
     "LICENSE"
   ],

package/skill/README.md

@@ -0,0 +1,14 @@
+# `privos-app-publish` Claude Skill
+
+This directory is the packaged Claude skill for publishing PrivOS MCP apps
+to the Marketplace with the `privos-app` CLI (shipped in this package's
+`bin`). It is not loaded automatically — `create-privos-mcp-app` copies it
+into a generated app's `.claude/skills/privos-app-publish/` at scaffold time.
+
+- `SKILL.md` — when to use, preconditions, exact commands, `--json` event
+  reading, approval-URL handoff, token-mode rules, exit codes.
+- `references/errors.md` — full error-code table and remediation.
+
+Keep this content in sync with the actual CLI flags/behavior in
+`src/cli/commands/publish.ts` and `src/cli/lib/*.ts` — it is generated from
+that source, not hand-invented.

package/skill/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: privos-app-publish
+description: Publish a PrivOS MCP app to the Marketplace using the `privos-app` CLI (package, lint, upload, version, submit) with either interactive browser approval or a CI publisher token.
+user-invocable: true
+when_to_use: "Invoke when the user asks to publish, release, or ship a new version of an MCP app to the PrivOS Marketplace."
+category: publishing
+keywords: [privos-app, marketplace, publish, mcp-app, cli]
+license: MIT
+argument-hint: "[app directory]"
+metadata:
+  author: privos
+  version: "1.0.0"
+---
+
+# PrivOS App Publish Skill
+
+Runs `privos-app publish` correctly from an MCP app folder. The CLI (shipped
+in `@privos_ai/app-server`, bin `privos-app`) is the only supported publish
+path — it is a scripted `npm publish`-shaped flow: package → lint → authorize
+→ upload → version → submit. Do not hand-drive Portal API calls or resurrect
+the retired `.mjs` publish scripts.
+
+## When to Use
+
+- The user asks to publish, release, or ship a new version of an MCP app to
+  the PrivOS Marketplace.
+- The user asks to check why a publish failed (see `references/errors.md`).
+
+Not for: editing listing content, pricing, screenshots, or Stripe Connect
+(all Creator Studio, web-only) — the CLI never touches those.
+
+## Preconditions (verify before running)
+
+1. **Clean git tree.** `privos-app publish` refuses a dirty working tree
+   unless `--allow-dirty` is passed. Prefer committing first; only use
+   `--allow-dirty` when the user explicitly wants an uncommitted snapshot
+   packaged.
+2. **Version bumped in BOTH files.** `privos-app.json` `version` and
+   `package.json` `version` must be equal (the CLI fast-fails otherwise,
+   `MANIFEST_IDENTITY_MISMATCH`) and must be a semver that has never been
+   published for this listing before — re-publishing an existing semver fails
+   with `VERSION_SEMVER_EXISTS`. Always bump both fields together.
+3. **Manifest passes structural lint.** Run `privos-app lint` (or let
+   `publish` run it — it lints as step 1) before attempting a full publish.
+4. **Catalog check.** Confirm this is genuinely a new version of an existing
+   listing or a legitimately new app — do not re-run publish blindly after a
+   failure without reading the error.
+
+## Exact Commands
+
+Run from the app's root directory (where `privos-app.json` lives):
+
+```bash
+# Preview only — packages the archive, prints its sha256, does not authorize or upload
+npx privos-app publish --dry-run
+
+# Interactive (default): prints an approval URL, waits for browser approval
+npx privos-app publish
+
+# Non-interactive / CI: requires PRIVOS_PUBLISHER_TOKEN in the environment
+PRIVOS_PUBLISHER_TOKEN=pvp_xxx npx privos-app publish --yes
+
+# Machine-readable event stream (one NDJSON object per line on stdout)
+npx privos-app publish --json
+```
+
+Useful flags: `--listing <slug>` (when the listing can't be resolved from the
+manifest name), `--changelog <text>` / `--changelog-file <path>`,
+`--allow-dirty`, `--portal <origin>` (default `https://portal.privos.io`),
+`--machine-label <text>` (shown on the approval page, never the hostname by
+default), `--cwd <path>`, `-h/--help`.
+
+## Reading `--json` Output
+
+Each line is one JSON object with an `event` field, emitted in this order:
+`lint` → `package` → (`authorization_token` | `authorization_device` →
+`authorization_approved`) → `upload_progress` (repeated) → `upload_complete`
+→ `version_created` → `submitted` → `status`. A run that fails emits `error`
+with `code` and `message` instead of continuing. Never print or log a `grant`
+or token value beyond what the CLI itself already masks — the CLI does not
+emit raw secrets in any event.
+
+## Handing the Approval URL to the User
+
+**The agent cannot click the approval link.** On `authorization_device`,
+print the `verificationUrl` and `userCode` verbatim to the user and ask them
+to open it in their own browser and log in to `client.privos.io` — do not
+attempt to fetch, curl, or "visit" the URL yourself. The CLI polls
+automatically after printing it; do not re-run `publish` while it is waiting.
+If the user says they approved but the CLI is still waiting, tell them to
+recheck they approved the correct listing/version shown on the page —
+approval is not automatic on click, it depends on identity match.
+
+## Token Mode (CI / Non-Interactive)
+
+`PRIVOS_PUBLISHER_TOKEN` must come from the environment only — never ask the
+user to paste a `pvp_…` token into chat, never write one into a command
+argument, file, or log. If the user wants CI mode but has no token yet, tell
+them to generate one from Creator Studio (a step-up action: email code or
+magic link, plus TOTP if their account has 2FA) and export it in their own
+shell/CI secret store before re-running. Token mode only works after the
+listing's first version was approved once interactively (see
+`LISTING_NOT_BOUND` below).
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Submitted (or reached a benign non-blocking status; see `references/errors.md`) |
+| 2 | Blocked by policy (manifest invalid, dirty tree, denied archive path, semver reused, preflight failed) |
+| 3 | Authorization denied, expired, or already consumed |
+| 4 | Network or Portal error |
+| 5 | Usage error (bad flags, cancelled prompt, not a git repository) |
+
+## After Submit
+
+The CLI has no `status` or `whoami` command. Once `submitted` prints, review
+progress (`PREFLIGHT_PENDING` → `SCAN` → `AI_REVIEW` → human `APPROVE` →
+build) is tracked only in Creator Studio on `client.privos.io`. Tell the user
+to check there — do not invent a polling loop or guess at review state.
+
+See `references/errors.md` for the full error-code table and remediation,
+including `VERSION_SEMVER_EXISTS`, `PREFLIGHT_FAILED` vs
+`PREFLIGHT_BLOCKED_INFRA` vs incomplete listing content.

package/skill/references/errors.md

@@ -0,0 +1,68 @@
+# `privos-app publish` Error Reference
+
+Every failure the CLI surfaces carries a `code` (visible in `--json` `error`
+events and in the human-readable message) and maps to one of the exit codes
+in `SKILL.md`. This table is generated from the CLI's actual error sites
+(`src/cli/commands/publish.ts`, `src/cli/lib/*.ts`) — do not hand-edit
+without checking the source stays in sync.
+
+## Manifest / packaging (exit 2 unless noted)
+
+| Code | Cause | Remediation |
+|---|---|---|
+| `MANIFEST_INVALID` | `privos-app.json` fails structural lint | Run `privos-app lint` and fix the reported fields |
+| `MANIFEST_IDENTITY_MISMATCH` | `name`/`version` differ between `privos-app.json` and `package.json` | Make both files agree exactly |
+| `NOT_GIT_REPOSITORY` (exit 5) | `--cwd` is not inside a git repo, or has no commits | Publish from a committed git checkout |
+| `DIRTY_TREE` | Uncommitted changes present, `--allow-dirty` not passed | Commit the intended files, or pass `--allow-dirty` deliberately |
+| `CREDENTIAL_FILE_FOUND` | A `.env.*`, `.pem`, `.key`, `id_rsa*`, or `*credentials*` file is in the working tree | Remove or relocate the file outside the packaged tree |
+| `GIT_ARCHIVE_FAILED` (exit 5) | `git read-tree`/`add`/`write-tree`/`archive` failed | Check the git error text printed alongside; usually a broken index or permissions issue |
+| `INVALID_ZIP` | Produced archive has no valid ZIP central directory | Re-run; if it repeats, file a bug — not user-fixable |
+| `MISSING_REQUIRED_ENTRY` | Archive is missing `privos-app.json` or `Dockerfile` at its root | Ensure both files are tracked (or present with `--allow-dirty`) at the repo root |
+| `DENIED_PATH_IN_ARCHIVE` | Archive contains `node_modules`, `dist`, `dist-source`, `.git`, `.privos/skills`, `.env*`, `..` traversal, or credential-like paths | Remove those paths from the tree/`.gitattributes export-ignore` before packaging |
+| `ENTRY_LIMIT_EXCEEDED` | Archive has more than 20,000 entries | Reduce tracked files or exclude generated assets |
+| `FILE_SIZE_EXCEEDED` | A single file exceeds 50 MB | Remove or externalize the oversized file |
+| `TOTAL_SIZE_EXCEEDED` | Archive exceeds 200 MB total | Trim the packaged tree |
+| `CANCELLED` (exit 5) | User declined the interactive confirmation prompt | Re-run and confirm, or pass `--yes` |
+
+## Authorization (exit 3 unless noted)
+
+| Code | Cause | Remediation |
+|---|---|---|
+| `LISTING_NOT_BOUND` (exit 2) | A publisher token was used but this listing has never had an interactively-approved first version | Run `privos-app publish` without a token once (browser approval) to bind the listing, then use the token for subsequent versions |
+| `LISTING_UNRESOLVED` (exit 2) | The Portal could not resolve a listing from the manifest name | Pass `--listing <slug>` |
+| `AUTHORIZATION_DENIED` | The approver declined the request on the approval page | Confirm with the user this was intentional; re-run to request a new approval if not |
+| `AUTHORIZATION_EXPIRED` | Nobody approved within the authorization's TTL (15 min) | Re-run `publish`; approve promptly this time |
+| `AUTHORIZATION_CONSUMED` | The device code was already used to mint a grant | Re-run `publish` to request a fresh authorization |
+| `PUBLISHER_TOKEN_INVALID` / `PUBLISHER_TOKEN_REVOKED` / `PUBLISHER_TOKEN_EXPIRED` (exit 3) | `PRIVOS_PUBLISHER_TOKEN` is malformed, revoked, or past its expiry | Generate a new token in Creator Studio (step-up required) and export it in the environment |
+
+## Upload / version / submit (exit 2 unless noted)
+
+| Code | Cause | Remediation |
+|---|---|---|
+| `PUBLISH_GRANT_EXPIRED` (exit 3) | The 60-minute grant expired mid-upload | Re-run `publish` to request a new approval; do not resume a stale grant |
+| `PUBLISH_GRANT_MISMATCH` | Uploaded archive sha256 or manifest name/version does not match what was approved | Re-run `publish` from a clean state — do not edit the archive after approval |
+| `VERSION_SEMVER_EXISTS` | This exact semver was already published for the listing | **Bump `version` in both `privos-app.json` and `package.json`**, then re-run |
+
+## Post-submit states (exit 0 — informational, not failures)
+
+`publish` waits up to 60 s after submit for the version to leave
+`PREFLIGHT_PENDING`, then prints one of:
+
+- **`PREFLIGHT_FAILED`** — the automated preflight scan rejected the archive
+  itself (manifest/runtime problems found in the uploaded content). The CLI
+  prints the findings verbatim (exit 2). Fix the flagged issue, bump the
+  version, and re-run `publish`.
+- **`PREFLIGHT_BLOCKED_INFRA`** — preflight cannot run because of
+  Portal-side build infrastructure capacity/availability, not anything wrong
+  with the submission (exit 0). Tell the user this is admin-side; no local
+  action fixes it — wait and check Creator Studio later.
+- **listing content incomplete** — a *different* gate than preflight: if the
+  Creator Studio listing itself is missing required metadata (categories,
+  screenshots, legal URLs), the submission can be accepted by the CLI but
+  stall in human review because the listing page is incomplete. This is not
+  a CLI error code — the CLI only packages and submits the version; finishing
+  the listing's content is done in Creator Studio, not via `privos-app`.
+- **`PREFLIGHT_PENDING`** (still pending after 60 s) or any other state —
+  printed as-is with "follow up in Creator Studio". The CLI has no `status`
+  command; all further review progress (`SCAN` → `AI_REVIEW` → human
+  `APPROVE` → build) is tracked only on `client.privos.io`.