@privos_ai/app-server 0.8.4 → 0.10.0

package/dist/ui/asset-filename-rule.js

@@ -0,0 +1,39 @@
+/**
+ * Content-hashed asset filename rule shared by the SDK (build-time validation,
+ * `readAsset` lookups) and the Hub route that re-serves these files. A filename
+ * must start with an alnum, may contain `.`/`_`/`-` up to a trailing `-<hash>`
+ * of at least 8 chars, then one of the allowed extensions. No `/`, no `..`, no
+ * `.map` — content hashing itself is guaranteed by the assets manifest listing
+ * a file, not by this regex alone.
+ */
+export const MCP_UI_ASSET_FILENAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*-[A-Za-z0-9_-]{8,}\.(js|css|svg|json|woff|woff2|ttf|png|jpg|jpeg|gif|webp|avif|ico|wasm|gz)$/;
+/** Extensions a split-build UI is ever allowed to publish under `assets/`. */
+export const MCP_UI_ASSET_EXTENSIONS = [
+    'js',
+    'css',
+    'svg',
+    'json',
+    'woff',
+    'woff2',
+    'ttf',
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'webp',
+    'avif',
+    'ico',
+    'wasm',
+    'gz',
+];
+/**
+ * `ui://<appSlug>/assets/` — the app-level (not per-entry-point) URI prefix
+ * every split asset is addressed under, per the wire contract.
+ */
+export function deriveAssetUriPrefix(appSlug) {
+    if (typeof appSlug !== 'string' || appSlug.trim().length === 0) {
+        throw new Error('deriveAssetUriPrefix requires a non-empty appSlug');
+    }
+    return `ui://${appSlug}/assets/`;
+}
+//# sourceMappingURL=asset-filename-rule.js.map

package/dist/ui/asset-filename-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-filename-rule.js","sourceRoot":"","sources":["../../src/ui/asset-filename-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACpC,yHAAyH,CAAC;AAE3H,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,IAAI;IACJ,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,OAAO;IACP,KAAK;IACL,KAAK;IACL,KAAK;IACL,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;IACN,IAAI;CACK,CAAC;AAIX;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IACnD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,QAAQ,OAAO,UAAU,CAAC;AAClC,CAAC"}

package/dist/ui/assets-manifest.d.ts

@@ -0,0 +1,19 @@
+export interface AssetManifestEntry {
+    name: string;
+    size: number;
+    type: string;
+}
+export interface AssetsManifest {
+    files: AssetManifestEntry[];
+}
+export declare function mimeTypeForAssetFile(fileName: string): string;
+/**
+ * Build `{ files: [{ name, size, type }] }` for `distDir/assets` — the union
+ * of Vite's `.vite/manifest.json` entries and a directory scan (lazy/CSS-only
+ * chunks and fonts never appear in the manifest). Every file actually present
+ * under `assets/` is validated: filename rule + extension allowlist, no
+ * `.map`, size ≤ 2 MB. Throws with the full list of offenders otherwise —
+ * this is boot-time validation, never a partial/best-effort manifest.
+ */
+export declare function buildAssetsManifest(distDir: string): AssetsManifest;
+//# sourceMappingURL=assets-manifest.d.ts.map

package/dist/ui/assets-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets-manifest.d.ts","sourceRoot":"","sources":["../../src/ui/assets-manifest.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC5B;AAwBD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG7D;AA4DD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CA4CnE"}

package/dist/ui/assets-manifest.js

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MCP_UI_ASSET_FILENAME_RE } from './asset-filename-rule.js';
+/** Matches the wire contract's per-asset cap; the SDK refuses larger at build time. */
+const MAX_ASSET_BYTES = 2 * 1024 * 1024;
+const MIME_BY_EXTENSION = {
+    js: 'text/javascript',
+    css: 'text/css',
+    svg: 'image/svg+xml',
+    json: 'application/json',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    ttf: 'font/ttf',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    ico: 'image/x-icon',
+    wasm: 'application/wasm',
+    gz: 'application/gzip',
+};
+export function mimeTypeForAssetFile(fileName) {
+    const ext = fileName.slice(fileName.lastIndexOf('.') + 1).toLowerCase();
+    return MIME_BY_EXTENSION[ext] ?? 'application/octet-stream';
+}
+/** Vite manifest paths are distDir-relative, e.g. `assets/index-H.js`. */
+function assetFileNameFromManifestPath(relativePath) {
+    if (typeof relativePath !== 'string')
+        return undefined;
+    const normalized = relativePath.replace(/\\/g, '/');
+    const prefix = 'assets/';
+    return normalized.startsWith(prefix) ? normalized.slice(prefix.length) : undefined;
+}
+function readViteManifestFileNames(distDir) {
+    const manifestPath = path.join(distDir, '.vite', 'manifest.json');
+    const names = new Set();
+    if (!fs.existsSync(manifestPath))
+        return names;
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`serveBuiltUi: failed to parse Vite manifest at ${manifestPath}: ${err.message}`);
+    }
+    if (!raw || typeof raw !== 'object')
+        return names;
+    for (const chunk of Object.values(raw)) {
+        if (!chunk || typeof chunk !== 'object')
+            continue;
+        const file = assetFileNameFromManifestPath(chunk.file);
+        if (file)
+            names.add(file);
+        if (Array.isArray(chunk.css)) {
+            for (const entry of chunk.css) {
+                const name = assetFileNameFromManifestPath(entry);
+                if (name)
+                    names.add(name);
+            }
+        }
+        if (Array.isArray(chunk.assets)) {
+            for (const entry of chunk.assets) {
+                const name = assetFileNameFromManifestPath(entry);
+                if (name)
+                    names.add(name);
+            }
+        }
+    }
+    return names;
+}
+function scanAssetsDirectory(assetsDir) {
+    const names = new Set();
+    if (!fs.existsSync(assetsDir))
+        return names;
+    for (const entry of fs.readdirSync(assetsDir)) {
+        if (fs.statSync(path.join(assetsDir, entry)).isFile())
+            names.add(entry);
+    }
+    return names;
+}
+/**
+ * Build `{ files: [{ name, size, type }] }` for `distDir/assets` — the union
+ * of Vite's `.vite/manifest.json` entries and a directory scan (lazy/CSS-only
+ * chunks and fonts never appear in the manifest). Every file actually present
+ * under `assets/` is validated: filename rule + extension allowlist, no
+ * `.map`, size ≤ 2 MB. Throws with the full list of offenders otherwise —
+ * this is boot-time validation, never a partial/best-effort manifest.
+ */
+export function buildAssetsManifest(distDir) {
+    const assetsDir = path.join(distDir, 'assets');
+    const fileNames = new Set([
+        ...readViteManifestFileNames(distDir),
+        ...scanAssetsDirectory(assetsDir),
+    ]);
+    const offenders = [];
+    const files = [];
+    for (const name of [...fileNames].sort()) {
+        const filePath = path.join(assetsDir, name);
+        if (name.endsWith('.map')) {
+            offenders.push(`${name}: sourcemaps must not be published under assets/`);
+            continue;
+        }
+        if (!MCP_UI_ASSET_FILENAME_RE.test(name)) {
+            offenders.push(`${name}: does not match the content-hashed filename rule`);
+            continue;
+        }
+        let stat;
+        try {
+            stat = fs.statSync(filePath);
+        }
+        catch {
+            offenders.push(`${name}: referenced by the build but missing from ${assetsDir}`);
+            continue;
+        }
+        if (stat.size > MAX_ASSET_BYTES) {
+            offenders.push(`${name}: ${stat.size} bytes exceeds the ${MAX_ASSET_BYTES} byte per-asset limit`);
+            continue;
+        }
+        files.push({ name, size: stat.size, type: mimeTypeForAssetFile(name) });
+    }
+    if (offenders.length > 0) {
+        throw new Error(`serveBuiltUi: invalid files under ${assetsDir}:\n${offenders.map((o) => `  - ${o}`).join('\n')}`);
+    }
+    return { files };
+}
+//# sourceMappingURL=assets-manifest.js.map

package/dist/ui/assets-manifest.js.map

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

package/dist/ui/serve-built-ui.d.ts

@@ -0,0 +1,28 @@
+import type { UiAssetContent } from '../runtime.js';
+import { type AssetsManifest } from './assets-manifest.js';
+export interface ServeBuiltUiOptions {
+    /** Absolute path to the Vite build output directory containing `index.html`, `assets/`, `.vite/manifest.json`. */
+    distDir: string;
+    /** The app's manifest id — used to derive `ui://<appSlug>/assets/…` URIs. */
+    appSlug: string;
+}
+export interface ServeBuiltUi {
+    /** Cached at construction: meta + watchdog + relative asset tags. */
+    renderHtml(): string;
+    /** `null` for an unrecognized/unlisted/traversal-unsafe URI. Cached after first successful read. */
+    readAsset(uri: string): UiAssetContent | null;
+    /** `{ files: [{ name, size, type }] }`, cached at construction. */
+    readAssetsManifest(): AssetsManifest;
+    /** `ui://<appSlug>/assets/` */
+    assetUriPrefix: string;
+}
+/**
+ * Serve a Vite-built (`base: './'`) app UI over MCP `resources/read`: the
+ * shell HTML (opt-in relay meta + inline boot watchdog) plus the hashed
+ * `assets/` files it references, split out of the HTML payload. Boot-time
+ * validation (asset filenames, extensions, size, no sourcemaps) and the shell's
+ * relative-asset-path assertion both throw at construction — a misconfigured
+ * build must fail loudly here, never serve a blank frame in production.
+ */
+export declare function serveBuiltUi(options: ServeBuiltUiOptions): ServeBuiltUi;
+//# sourceMappingURL=serve-built-ui.d.ts.map

package/dist/ui/serve-built-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-built-ui.d.ts","sourceRoot":"","sources":["../../src/ui/serve-built-ui.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAUhF,MAAM,WAAW,mBAAmB;IACnC,kHAAkH;IAClH,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC5B,qEAAqE;IACrE,UAAU,IAAI,MAAM,CAAC;IACrB,oGAAoG;IACpG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IAC9C,mEAAmE;IACnE,kBAAkB,IAAI,cAAc,CAAC;IACrC,+BAA+B;IAC/B,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAgDvE"}

package/dist/ui/serve-built-ui.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { deriveAssetUriPrefix } from './asset-filename-rule.js';
+import { buildAssetsManifest } from './assets-manifest.js';
+import { MCP_UI_SHELL_WATCHDOG_SCRIPT } from './shell-watchdog.js';
+const TEXT_ASSET_EXTENSIONS = new Set(['js', 'css', 'svg', 'json']);
+const PRIVOS_UI_ASSETS_META = '<meta name="privos-ui-assets" content="relay">';
+const PRIVOS_UI_ASSETS_META_RE = /<meta\b[^>]*\bname\s*=\s*["']privos-ui-assets["'][^>]*\bcontent\s*=\s*["']relay["']|<meta\b[^>]*\bcontent\s*=\s*["']relay["'][^>]*\bname\s*=\s*["']privos-ui-assets["']/i;
+const ASSET_TAG_RE = /<(script|link)\b[^>]*>/gi;
+const SRC_OR_HREF_RE = /\b(?:src|href)\s*=\s*(["'])(.*?)\1/i;
+/**
+ * Serve a Vite-built (`base: './'`) app UI over MCP `resources/read`: the
+ * shell HTML (opt-in relay meta + inline boot watchdog) plus the hashed
+ * `assets/` files it references, split out of the HTML payload. Boot-time
+ * validation (asset filenames, extensions, size, no sourcemaps) and the shell's
+ * relative-asset-path assertion both throw at construction — a misconfigured
+ * build must fail loudly here, never serve a blank frame in production.
+ */
+export function serveBuiltUi(options) {
+    const { distDir, appSlug } = options;
+    const assetUriPrefix = deriveAssetUriPrefix(appSlug);
+    const assetsDir = path.join(distDir, 'assets');
+    // Boot-time validation of every file under assets/ — throws with the full
+    // offender list on filename-rule / extension / size / sourcemap violations.
+    const manifest = buildAssetsManifest(distDir);
+    const manifestFiles = new Map(manifest.files.map((file) => [file.name, file]));
+    const assetsDirRealpath = fs.existsSync(assetsDir) ? fs.realpathSync(assetsDir) : undefined;
+    const html = renderShellHtml(distDir);
+    const assetCache = new Map();
+    return {
+        renderHtml() {
+            return html;
+        },
+        readAsset(uri) {
+            const cached = assetCache.get(uri);
+            if (cached)
+                return cached;
+            if (!uri.startsWith(assetUriPrefix))
+                return null;
+            const fileName = uri.slice(assetUriPrefix.length);
+            const entry = manifestFiles.get(fileName);
+            if (!entry || !assetsDirRealpath)
+                return null;
+            const filePath = path.join(assetsDir, fileName);
+            let realFilePath;
+            try {
+                realFilePath = fs.realpathSync(filePath);
+            }
+            catch {
+                return null;
+            }
+            if (!isContainedIn(assetsDirRealpath, realFilePath))
+                return null;
+            const ext = fileName.slice(fileName.lastIndexOf('.') + 1).toLowerCase();
+            const resource = TEXT_ASSET_EXTENSIONS.has(ext)
+                ? { uri, mimeType: entry.type, text: fs.readFileSync(realFilePath, 'utf8') }
+                : { uri, mimeType: entry.type, blob: fs.readFileSync(realFilePath).toString('base64') };
+            assetCache.set(uri, resource);
+            return resource;
+        },
+        readAssetsManifest() {
+            return manifest;
+        },
+        assetUriPrefix,
+    };
+}
+function isContainedIn(dirRealpath, fileRealpath) {
+    const relative = path.relative(dirRealpath, fileRealpath);
+    return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function renderShellHtml(distDir) {
+    const indexPath = path.join(distDir, 'index.html');
+    let raw;
+    try {
+        raw = fs.readFileSync(indexPath, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`serveBuiltUi: cannot read ${indexPath}: ${err.message}`);
+    }
+    assertRelativeAssetTags(raw, indexPath);
+    let html = raw;
+    if (!PRIVOS_UI_ASSETS_META_RE.test(html)) {
+        html = injectIntoHead(html, `  ${PRIVOS_UI_ASSETS_META}\n`, { atStart: false });
+    }
+    html = injectIntoHead(html, `  <script>${MCP_UI_SHELL_WATCHDOG_SCRIPT}</script>\n`, { atStart: true });
+    return html;
+}
+/**
+ * Every `<script src>` / `<link href>` in the shell must be relative
+ * (`./assets/…` or `assets/…`). An absolute or external reference means the
+ * app was built without Vite `base: './'` and would resolve against the
+ * wrong origin once the tab renders it — fail construction, not the frame.
+ */
+function assertRelativeAssetTags(html, indexPath) {
+    const offenders = [];
+    ASSET_TAG_RE.lastIndex = 0;
+    let tagMatch;
+    while ((tagMatch = ASSET_TAG_RE.exec(html))) {
+        const tag = tagMatch[0];
+        const refMatch = SRC_OR_HREF_RE.exec(tag);
+        if (!refMatch)
+            continue;
+        const ref = refMatch[2];
+        if (ref && (ref.startsWith('./assets/') || ref.startsWith('assets/')))
+            continue;
+        offenders.push(tag.length > 120 ? `${tag.slice(0, 117)}...` : tag);
+    }
+    if (offenders.length > 0) {
+        throw new Error(`serveBuiltUi: ${indexPath} has non-relative asset references — build with Vite base: './':\n${offenders
+            .map((o) => `  - ${o}`)
+            .join('\n')}`);
+    }
+}
+function injectIntoHead(html, snippet, opts) {
+    if (opts.atStart) {
+        const headOpen = /<head[^>]*>/i.exec(html);
+        if (headOpen) {
+            const insertAt = headOpen.index + headOpen[0].length;
+            return `${html.slice(0, insertAt)}\n${snippet}${html.slice(insertAt)}`;
+        }
+    }
+    else {
+        const headCloseIdx = html.search(/<\/head>/i);
+        if (headCloseIdx !== -1) {
+            return html.slice(0, headCloseIdx) + snippet + html.slice(headCloseIdx);
+        }
+    }
+    // No <head> tag found in a well-formed Vite build — fall back to prepending.
+    return snippet + html;
+}
+//# sourceMappingURL=serve-built-ui.js.map

package/dist/ui/serve-built-ui.js.map

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

package/dist/ui/shell-watchdog.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Inline boot watchdog injected at the top of `<head>`. No dependencies, runs
+ * before any other script/link tag so its capture-phase `error` listener is
+ * registered before those tags start loading. Two failure signals:
+ *   - a script/link `error` event (asset 404/network failure), or
+ *   - a 10 s timeout without `window.__privosUiBooted` being set by the app's
+ *     own bootstrap once it renders.
+ * Either one replaces `#root` (or `document.body`) with a visible retry panel
+ * and notifies the host frame via `postMessage` so the Hub can log it.
+ */
+export declare const MCP_UI_SHELL_WATCHDOG_SCRIPT = "(function(){\nfunction fail(){\nif(window.__privosUiBooted)return;\nvar root=document.getElementById('root')||document.body;\nif(root){root.innerHTML='<div style=\"font:14px system-ui;padding:24px;text-align:center\">App assets unavailable \u2014 <button onclick=\"location.reload()\">Retry</button></div>';}\ntry{parent.postMessage({method:'ui/asset-load-failed'},'*');}catch(e){}\n}\nwindow.addEventListener('error',function(e){\nvar t=e&&e.target;\nif(!t||(t.tagName!=='SCRIPT'&&t.tagName!=='LINK'))return;\nfail();\n},true);\nsetTimeout(fail,10000);\n})();";
+//# sourceMappingURL=shell-watchdog.d.ts.map

package/dist/ui/shell-watchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-watchdog.d.ts","sourceRoot":"","sources":["../../src/ui/shell-watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,qjBAanC,CAAC"}

package/dist/ui/shell-watchdog.js

@@ -0,0 +1,25 @@
+/**
+ * Inline boot watchdog injected at the top of `<head>`. No dependencies, runs
+ * before any other script/link tag so its capture-phase `error` listener is
+ * registered before those tags start loading. Two failure signals:
+ *   - a script/link `error` event (asset 404/network failure), or
+ *   - a 10 s timeout without `window.__privosUiBooted` being set by the app's
+ *     own bootstrap once it renders.
+ * Either one replaces `#root` (or `document.body`) with a visible retry panel
+ * and notifies the host frame via `postMessage` so the Hub can log it.
+ */
+export const MCP_UI_SHELL_WATCHDOG_SCRIPT = `(function(){
+function fail(){
+if(window.__privosUiBooted)return;
+var root=document.getElementById('root')||document.body;
+if(root){root.innerHTML='<div style="font:14px system-ui;padding:24px;text-align:center">App assets unavailable — <button onclick="location.reload()">Retry</button></div>';}
+try{parent.postMessage({method:'ui/asset-load-failed'},'*');}catch(e){}
+}
+window.addEventListener('error',function(e){
+var t=e&&e.target;
+if(!t||(t.tagName!=='SCRIPT'&&t.tagName!=='LINK'))return;
+fail();
+},true);
+setTimeout(fail,10000);
+})();`;
+//# sourceMappingURL=shell-watchdog.js.map

package/dist/ui/shell-watchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-watchdog.js","sourceRoot":"","sources":["../../src/ui/shell-watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;;;;;;;;;;;;;MAatC,CAAC"}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@privos_ai/app-server",
-  "version": "0.8.4",
+  "version": "0.10.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.