@wenrwa/marketplace-cli 0.8.10 → 0.8.11

package/dist/__tests__/bridge-preview-python.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/bridge-preview-python.test.js

@@ -0,0 +1,287 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * tp-21 — Team preview runs Python apps directly (no package.json launcher).
+ *
+ * Pure: planPreview decides the steps and start command from the checkout.
+ * Real: a bare remote holding a Python app, run through PreviewRunner with the
+ * machine's own uv + python3 (skipped when this machine has no uv). Every
+ * server is stopped by exact PID in teardown (runner.shutdown).
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const previewCheckout_1 = require("../bridge/previewCheckout");
+jest.setTimeout(180_000);
+function checkout(files) {
+    return {
+        has: (n) => Object.prototype.hasOwnProperty.call(files, n),
+        read: (n) => (Object.prototype.hasOwnProperty.call(files, n) ? files[n] : null),
+    };
+}
+const CTX = { slotDir: '/data/previews/ws/a', toolsDir: '/data/previews/.tools', uv: '/usr/bin/uv', basePath: '/usr/bin:/bin' };
+const PROJECT = '[project]\nname = "app"\nversion = "0.1.0"\ndependencies = []\n';
+describe('planPreview (tp-21)', () => {
+    it('package.json keeps the Node path even with Python files beside it', () => {
+        const r = (0, previewCheckout_1.planPreview)(checkout({
+            'package.json': JSON.stringify({ scripts: { build: 'sh preview/build.sh', start: 'sh preview/start.sh' } }),
+            'pyproject.toml': `${PROJECT}[tool.hiveop.preview]\nstart = "python app.py"\n`,
+            'uv.lock': '',
+        }), 'built', CTX);
+        expect(r).toEqual({ ok: true, plan: { kind: 'node', steps: [['npm', ['install']], ['npm', ['run', 'build']]], start: ['npm', ['run', 'start']], env: {} } });
+    });
+    it('package.json without the script is still no_start_script', () => {
+        expect((0, previewCheckout_1.planPreview)(checkout({ 'package.json': '{"scripts":{}}' }), 'built', CTX)).toMatchObject({ ok: false, reason: 'no_start_script' });
+    });
+    it('no package.json and no Python project is no_package_json', () => {
+        expect((0, previewCheckout_1.planPreview)(checkout({ 'README.md': 'hi', Procfile: 'web: python app.py' }), 'built', CTX))
+            .toMatchObject({ ok: false, reason: 'no_package_json' });
+    });
+    it('uv.lock → uv sync --frozen, and the pyproject start command runs through sh', () => {
+        const r = (0, previewCheckout_1.planPreview)(checkout({
+            'pyproject.toml': `${PROJECT}\n[tool.hiveop.preview]\nstart = "uvicorn app:app --host $HOST --port $PORT"\nbuild = 'python manage.py collectstatic --noinput'\n`,
+            'uv.lock': 'version = 1',
+        }), 'built', CTX);
+        expect(r.ok && r.plan).toEqual({
+            kind: 'python',
+            steps: [
+                ['/usr/bin/uv', ['sync', '--frozen', '--no-dev']],
+                ['sh', ['-c', 'python manage.py collectstatic --noinput']],
+            ],
+            start: ['sh', ['-c', 'uvicorn app:app --host $HOST --port $PORT']],
+            env: {
+                PATH: '/data/previews/ws/a/.venv/bin:/data/previews/.tools/bin:/usr/bin:/bin',
+                VIRTUAL_ENV: '/data/previews/ws/a/.venv',
+                UV_PROJECT_ENVIRONMENT: '/data/previews/ws/a/.venv',
+                UV_CACHE_DIR: '/data/previews/.tools/uv-cache',
+                UV_PYTHON_INSTALL_DIR: '/data/previews/.tools/python',
+                UV_PYTHON_PREFERENCE: 'system',
+                PYTHONUNBUFFERED: '1',
+            },
+        });
+    });
+    it('dev mode skips the pyproject build step', () => {
+        const r = (0, previewCheckout_1.planPreview)(checkout({ 'pyproject.toml': `${PROJECT}[tool.hiveop.preview]\nstart = "python app.py"\nbuild = "make"\n` }), 'dev', CTX);
+        expect(r.ok && r.plan.steps).toEqual([['/usr/bin/uv', ['sync', '--no-dev']]]);
+    });
+    it('requirements.txt → uv venv + uv pip install, started from the Procfile web line', () => {
+        const r = (0, previewCheckout_1.planPreview)(checkout({ 'requirements.txt': 'flask\n', Procfile: 'worker: python jobs.py\nweb: gunicorn app:app -b 127.0.0.1:$PORT\n' }), 'built', CTX);
+        expect(r.ok && r.plan.steps).toEqual([
+            ['/usr/bin/uv', ['venv', '--allow-existing', '/data/previews/ws/a/.venv']],
+            ['/usr/bin/uv', ['pip', 'install', '-r', 'requirements.txt']],
+        ]);
+        expect(r.ok && r.plan.start).toEqual(['sh', ['-c', 'gunicorn app:app -b 127.0.0.1:$PORT']]);
+    });
+    it('a tool-config-only pyproject beside requirements.txt uses the requirements path', () => {
+        const r = (0, previewCheckout_1.planPreview)(checkout({ 'pyproject.toml': '[tool.ruff]\nline-length = 100\n', 'requirements.txt': '', Procfile: 'web: python app.py' }), 'built', CTX);
+        expect(r.ok && r.plan.steps.map(([, a]) => a[0])).toEqual(['venv', 'pip']);
+    });
+    it('pyproject start wins over the Procfile', () => {
+        const r = (0, previewCheckout_1.planPreview)(checkout({ 'pyproject.toml': `${PROJECT}[tool.hiveop.preview]\nstart = "python a.py"\n`, Procfile: 'web: python b.py' }), 'built', CTX);
+        expect(r.ok && r.plan.start).toEqual(['sh', ['-c', 'python a.py']]);
+    });
+    it('no start command is refused no_start_command, never guessed', () => {
+        const r = (0, previewCheckout_1.planPreview)(checkout({ 'pyproject.toml': PROJECT, 'uv.lock': '', 'main.py': 'print(1)', Procfile: 'worker: x' }), 'built', CTX);
+        expect(r).toMatchObject({ ok: false, reason: 'no_start_command' });
+        expect(!r.ok && r.message).toMatch(/\[tool\.hiveop\.preview\]/);
+    });
+    it('no uv on the box → install the pinned uv into the persistent tools dir first, and run that one', () => {
+        const r = (0, previewCheckout_1.planPreview)(checkout({ 'requirements.txt': '', Procfile: 'web: python app.py' }), 'built', { ...CTX, uv: null });
+        expect(r.ok && r.plan.steps[0]).toEqual(['sh', ['-c',
+                `curl -LsSf https://astral.sh/uv/${previewCheckout_1.PREVIEW_UV_VERSION}/install.sh | env UV_INSTALL_DIR="/data/previews/.tools/bin" UV_NO_MODIFY_PATH=1 sh`]]);
+        expect(r.ok && r.plan.steps[1][0]).toBe('/data/previews/.tools/bin/uv');
+    });
+});
+describe('pyproject / Procfile readers (tp-21)', () => {
+    it('reads only [tool.hiveop.preview] string keys', () => {
+        const toml = [
+            '[project]', 'start = "not this"',
+            '[tool.hiveop.preview]  # preview', 'start = "python -m app --msg \\"hi\\""  # trailing', "build = 'make all'", 'port = 1',
+            '[tool.other]', 'start = "nor this"',
+        ].join('\n');
+        expect((0, previewCheckout_1.readHiveopPreviewTable)(toml)).toEqual({ start: 'python -m app --msg "hi"', build: 'make all' });
+        expect((0, previewCheckout_1.readHiveopPreviewTable)(PROJECT)).toEqual({});
+    });
+    it('procfileWeb takes the web line only', () => {
+        expect((0, previewCheckout_1.procfileWeb)('release: migrate\nweb:  python app.py  \n')).toBe('python app.py');
+        expect((0, previewCheckout_1.procfileWeb)('worker: x\n')).toBeNull();
+    });
+    it('findUv: PATH, then ~/.local/bin, then the tools dir', () => {
+        const exec = (set) => (p) => set.includes(p);
+        expect((0, previewCheckout_1.findUv)('/a:/b', '/home/w', '/t', exec(['/b/uv', '/home/w/.local/bin/uv']))).toBe('/b/uv');
+        expect((0, previewCheckout_1.findUv)('/a', '/home/w', '/t', exec(['/home/w/.local/bin/uv', '/t/bin/uv']))).toBe('/home/w/.local/bin/uv');
+        expect((0, previewCheckout_1.findUv)('/a', '/home/w', '/t', exec(['/t/bin/uv']))).toBe('/t/bin/uv');
+        expect((0, previewCheckout_1.findUv)('/a', '/home/w', '/t', exec([]))).toBeNull();
+    });
+});
+// ── real git + real uv + real python3 ────────────────────────────────────────
+const HAS_UV = !!(0, previewCheckout_1.findUv)(process.env.PATH, process.env.HOME, '/nonexistent');
+const realIt = HAS_UV ? it : it.skip;
+function git(cwd, ...args) {
+    return (0, child_process_1.execFileSync)('git', args, {
+        cwd, encoding: 'utf8',
+        env: { ...process.env, GIT_AUTHOR_NAME: 't', GIT_AUTHOR_EMAIL: 't@t', GIT_COMMITTER_NAME: 't', GIT_COMMITTER_EMAIL: 't@t' },
+    });
+}
+function freePort() {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.listen(0, '127.0.0.1', () => {
+            const port = srv.address().port;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+function get(port) {
+    return new Promise((resolve, reject) => {
+        http.get({ host: '127.0.0.1', port, path: '/' }, (res) => {
+            let body = '';
+            res.on('data', (c) => (body += c));
+            res.on('end', () => resolve(body));
+        }).on('error', reject);
+    });
+}
+// Standard library only: no network needed for an empty dependency set.
+const SERVER_PY = `
+import json, os, sys
+from http.server import BaseHTTPRequestHandler, HTTPServer
+class H(BaseHTTPRequestHandler):
+    def do_GET(self):
+        body = json.dumps({
+            "message": open("message.txt").read().strip(),
+            "secret": os.environ.get("OWNER_SECRET"),
+            "bridgeToken": os.environ.get("WENRWA_CONNECT_TOKEN"),
+            "inVenv": sys.prefix != sys.base_prefix,
+            "port": os.environ.get("PORT"),
+        }).encode()
+        self.send_response(200); self.end_headers(); self.wfile.write(body)
+    def log_message(self, *a): pass
+HTTPServer((os.environ.get("BIND", os.environ["HOST"]), int(os.environ["PORT"])), H).serve_forever()
+`;
+describe('PreviewRunner (tp-21) — a Python app, real uv', () => {
+    let root;
+    let remote;
+    let author;
+    let port;
+    let runner;
+    let previews;
+    function push(files, msg) {
+        for (const [name, content] of Object.entries(files)) {
+            const p = path.join(author, name);
+            if (content === null)
+                fs.rmSync(p, { force: true });
+            else
+                fs.writeFileSync(p, content);
+        }
+        git(author, 'add', '-A');
+        git(author, 'commit', '-m', msg);
+        git(author, 'push', 'origin', 'main');
+        return git(author, 'rev-parse', 'HEAD').trim();
+    }
+    beforeEach(async () => {
+        root = fs.mkdtempSync(path.join(os.tmpdir(), 'tp21-'));
+        remote = path.join(root, 'remote.git');
+        author = path.join(root, 'author');
+        previews = path.join(root, 'previews');
+        git(root, 'init', '--bare', '-b', 'main', remote);
+        fs.mkdirSync(author);
+        git(author, 'init', '-b', 'main');
+        git(author, 'remote', 'add', 'origin', remote);
+        fs.writeFileSync(path.join(author, '.gitignore'), '.env\n');
+        fs.writeFileSync(path.join(author, 'server.py'), SERVER_PY);
+        fs.writeFileSync(path.join(author, 'message.txt'), 'py v1\n');
+        fs.writeFileSync(path.join(author, 'requirements.txt'), '# stdlib only\n');
+        fs.writeFileSync(path.join(author, 'Procfile'), 'web: python server.py\n');
+        git(author, 'add', '-A');
+        git(author, 'commit', '-m', 'v1');
+        git(author, 'push', 'origin', 'main');
+        const wc = path.join(root, 'repos', 'ws-1');
+        fs.mkdirSync(path.dirname(wc), { recursive: true });
+        git(root, 'clone', remote, wc);
+        fs.writeFileSync(path.join(wc, '.env'), 'OWNER_SECRET=sk_live_owner_value\n');
+        port = await freePort();
+        runner = new previewCheckout_1.PreviewRunner({
+            previewsBaseDir: previews,
+            workingCopyDir: (ws) => path.join(root, 'repos', ws),
+            port,
+            baseEnv: { ...process.env, WENRWA_CONNECT_TOKEN: 'bridge-connect-token' },
+            readyTimeoutMs: { built: 20_000, dev: 20_000 },
+            probeIntervalMs: 100,
+            killGraceMs: 1_000,
+        });
+    });
+    afterEach(async () => {
+        await runner.shutdown();
+        fs.rmSync(root, { recursive: true, force: true });
+    });
+    realIt('requirements.txt + Procfile: serves from its venv with the owner .env and no bridge secrets; uv cache on the tools dir', async () => {
+        const head = git(author, 'rev-parse', 'HEAD').trim();
+        const r = await runner.start({ workspaceId: 'ws-1', repoUrl: remote });
+        expect(r).toMatchObject({ status: 'running', sha: head, runningSha: head });
+        expect(JSON.parse(await get(port))).toEqual({
+            message: 'py v1', secret: 'sk_live_owner_value', bridgeToken: null, inVenv: true, port: String(port),
+        });
+        expect(fs.existsSync(path.join(previews, '.tools', 'uv-cache'))).toBe(true);
+    });
+    realIt('pyproject [tool.hiveop.preview] start, uv sync; a start that dies on update keeps the old Python version serving', async () => {
+        const v2 = push({
+            'requirements.txt': null, Procfile: null,
+            'pyproject.toml': `${PROJECT}requires-python = ">=3.8"\n\n[tool.hiveop.preview]\nstart = "python server.py"\n`,
+            'message.txt': 'py v2 pyproject\n',
+        }, 'pyproject');
+        expect(await runner.start({ workspaceId: 'ws-1', repoUrl: remote })).toMatchObject({ status: 'running', runningSha: v2 });
+        expect(JSON.parse(await get(port))).toMatchObject({ message: 'py v2 pyproject', inVenv: true });
+        const dead = push({ 'pyproject.toml': `${PROJECT}\n[tool.hiveop.preview]\nstart = "python -c 'raise SystemExit(3)'"\n` }, 'dies');
+        const r = await runner.update({ workspaceId: 'ws-1', repoUrl: remote });
+        expect(r).toMatchObject({ status: 'start_failed', sha: dead, runningSha: v2 });
+        expect(JSON.parse(await get(port))).toMatchObject({ message: 'py v2 pyproject', inVenv: true });
+    });
+    realIt('no start command → failed / no_start_command, nothing started', async () => {
+        push({ Procfile: null }, 'no procfile');
+        const r = await runner.start({ workspaceId: 'ws-1', repoUrl: remote });
+        expect(r).toMatchObject({ status: 'failed', reason: 'no_start_command' });
+        await expect(get(port)).rejects.toThrow();
+    });
+    realIt('SECURITY: a Python app binding every interface is refused unsupported_bind', async () => {
+        push({ Procfile: 'web: BIND=0.0.0.0 python server.py\n' }, 'wild');
+        const r = await runner.start({ workspaceId: 'ws-1', repoUrl: remote });
+        expect(r).toMatchObject({ status: 'failed', reason: 'unsupported_bind' });
+        await expect(get(port)).rejects.toThrow();
+    });
+});

package/dist/__tests__/bridge-storage-quota-fetch.test.js

@@ -34,6 +34,8 @@ describe('fetchStorageQuotaFact', () => {
             additionalGb: 5,
             suggestedTier: null,
             suggestedCapGb: null,
+            tierName: null,
+            suggestedTierName: null,
         });
     });
     it('a blocked (409 STORAGE_QUOTA_EXCEEDED) response resolves the full blocked fact from the error body', async () => {
@@ -68,8 +70,38 @@ describe('fetchStorageQuotaFact', () => {
             additionalGb: 10,
             suggestedTier: 'pro_plus',
             suggestedCapGb: 50,
+            tierName: null,
+            suggestedTierName: null,
         });
     });
+    it("reads the backend's plan display names when present", async () => {
+        const fetchImpl = fakeFetch(() => ({
+            ok: false,
+            status: 409,
+            body: {
+                success: false,
+                error: {
+                    code: 'STORAGE_QUOTA_EXCEEDED',
+                    tier: 'payg',
+                    tierName: 'Pay-as-you-go',
+                    capGb: 2,
+                    usedGb: 4,
+                    additionalGb: 0.023,
+                    suggestedTier: 'pro',
+                    suggestedTierName: 'Pro',
+                    suggestedCapGb: 25,
+                },
+            },
+        }));
+        const fact = await (0, storageQuotaFetch_1.fetchStorageQuotaFact)({
+            apiUrl: 'https://api.test',
+            connectToken: 'tok-1',
+            usedGb: 3.96,
+            additionalGb: 0.0232,
+            fetchImpl,
+        });
+        expect(fact).toMatchObject({ tier: 'payg', tierName: 'Pay-as-you-go', suggestedTier: 'pro', suggestedTierName: 'Pro' });
+    });
     it('sends the Connect Token as a bearer header and the usage as query params', async () => {
         let seenUrl = '';
         let seenHeaders = {};

package/dist/__tests__/bridge-storage-quota-preflight.test.js

@@ -64,6 +64,55 @@ describe('storageQuotaPreflightMessage — pure message builder', () => {
         expect(msg.toLowerCase()).not.toMatch(/free up|reclaim/);
     });
 });
+describe('storageQuotaPreflightMessage — human numbers and plan names (owner report 2026-10-24)', () => {
+    const OWNER_FACT = {
+        allowed: false,
+        tier: 'payg',
+        tierName: 'Pay-as-you-go',
+        capGb: 2,
+        usedGb: 3.9614562988281125,
+        additionalGb: 0.023197174072265625,
+        suggestedTier: 'pro',
+        suggestedTierName: 'Pro',
+        suggestedCapGb: 25,
+    };
+    // Pinned copy of the arena's lib/storageRefusal.ts roundRefusalNumbers —
+    // the pane still runs it over this text, so it must leave it intact.
+    const arenaRound = (m) => m.replace(/(about )?(\d+\.\d{2,})/g, (_x, about, n) => {
+        const v = Number(n);
+        if (v > 0 && v < 0.1)
+            return 'under 0.1';
+        return (about ?? '') + v.toFixed(1).replace(/\.0$/, '');
+    });
+    it('the exact reported refusal reads as one decimal / "under 0.1" with display names', () => {
+        const msg = (0, storageQuotaPreflight_1.storageQuotaPreflightMessage)({ kind: 'over-quota', fact: OWNER_FACT });
+        expect(msg).toBe("Your Pay-as-you-go plan allows 2 GB — you're already using about 4.0 GB " +
+            'and this clone needs under 0.1 GB more. Upgrade to Pro (25 GB) to fit it.');
+    });
+    it("the arena's roundRefusalNumbers leaves the new text unchanged", () => {
+        const msg = (0, storageQuotaPreflight_1.storageQuotaPreflightMessage)({ kind: 'over-quota', fact: OWNER_FACT });
+        expect(arenaRound(msg)).toBe(msg);
+    });
+    it('a backend that already rounded (4, 0.023) gives the same sentence', () => {
+        const msg = (0, storageQuotaPreflight_1.storageQuotaPreflightMessage)({ kind: 'over-quota', fact: { ...OWNER_FACT, usedGb: 4, additionalGb: 0.023 } });
+        expect(msg).toContain('about 4.0 GB');
+        expect(msg).toContain('under 0.1 GB more');
+    });
+    it('an older backend without names falls back to the raw tier id', () => {
+        const msg = (0, storageQuotaPreflight_1.storageQuotaPreflightMessage)({
+            kind: 'over-quota',
+            fact: { ...OWNER_FACT, tierName: undefined, suggestedTierName: undefined },
+        });
+        expect(msg).toContain('Your payg plan');
+        expect(msg).toContain('Upgrade to pro (25 GB)');
+    });
+    it('aboutGb: one decimal, "under 0.1" for a positive sliver', () => {
+        expect((0, storageQuotaPreflight_1.aboutGb)(5.756542205810547)).toBe('about 5.8 GB');
+        expect((0, storageQuotaPreflight_1.aboutGb)(0.1)).toBe('about 0.1 GB');
+        expect((0, storageQuotaPreflight_1.aboutGb)(0.0999)).toBe('under 0.1 GB');
+        expect((0, storageQuotaPreflight_1.aboutGb)(25)).toBe('about 25.0 GB');
+    });
+});
 describe('CLONE_QUOTA_PREFLIGHT_REFUSED — distinct from the free-space code', () => {
     it('is a real, distinct string from CLONE_SPACE_PREFLIGHT_REFUSED', () => {
         expect(storageQuotaPreflight_1.CLONE_QUOTA_PREFLIGHT_REFUSED).toBeTruthy();

package/dist/bridge/previewCheckout.d.ts

@@ -8,7 +8,9 @@ export type PreviewStatus = 'stopped'
  | 'start_failed'
 /** Nothing could be attempted (see `reason`). */
  | 'failed';
-export type PreviewFailReason = 'busy_other_workspace' | 'no_repo_url' | 'git_failed' | 'no_package_json' | 'no_start_script' | 'port_in_use'
+export type PreviewFailReason = 'busy_other_workspace' | 'no_repo_url' | 'git_failed' | 'no_package_json' | 'no_start_script'
+/** tp-21 — a Python app with no `[tool.hiveop.preview] start` and no Procfile `web:` line. */
+ | 'no_start_command' | 'port_in_use'
 /** The app listened beyond 127.0.0.1 and could not be forced to loopback. */
  | 'unsupported_bind';
 export interface PreviewResult {
@@ -56,6 +58,8 @@ export interface PreviewRunnerOpts {
     killGraceMs?: number;
     /** This machine's non-loopback addresses (the bind check). Default: os.networkInterfaces(). */
     externalAddresses?: () => string[];
+    /** tp-21 — uv, its cache and fetched Pythons. Default `<previewsBaseDir>/.tools` (persistent). */
+    toolsDir?: string;
 }
 /** The only names a preview process takes from the bridge's own env. */
 /** The only address a preview app may listen on. */
@@ -94,6 +98,53 @@ export declare function listensBeyondLoopback(port: number, addresses: string[],
 export declare function parseSymrefHead(lsRemoteOutput: string): string | null;
 /** Which install command a checkout wants, by lockfile. */
 export declare function installCommand(files: (name: string) => boolean): [string, string[]];
+export type PreviewCommand = [string, string[]];
+/** Everything a deploy runs, in order, decided from the checkout alone. */
+export interface PreviewPlan {
+    kind: 'node' | 'python';
+    /** Install, then build — each must exit 0. */
+    steps: PreviewCommand[];
+    start: PreviewCommand;
+    /** Added on top of the preview env for every step and the server (forced, after the repo .env). */
+    env: Record<string, string>;
+}
+export type PreviewPlanResult = {
+    ok: true;
+    plan: PreviewPlan;
+} | {
+    ok: false;
+    reason: 'no_package_json' | 'no_start_script' | 'no_start_command';
+    message: string;
+};
+export interface PreviewCheckoutFiles {
+    has(name: string): boolean;
+    /** File text, or null when absent/unreadable. */
+    read(name: string): string | null;
+}
+export interface PreviewPlanContext {
+    /** Absolute checkout dir (the venv lives at `<slotDir>/.venv`). */
+    slotDir: string;
+    /** Persistent tools dir (uv binary, uv cache, fetched Pythons). */
+    toolsDir: string;
+    /** An existing uv executable, or null to install one into `<toolsDir>/bin`. */
+    uv: string | null;
+    /** The PATH the preview env starts from. */
+    basePath?: string;
+}
+/** The uv release the runner installs when the box has none (pinned: one known installer). */
+export declare const PREVIEW_UV_VERSION = "0.13.0";
+/** `[tool.hiveop.preview]` string keys from pyproject.toml text. Only plain `key = "…"` / `key = '…'` lines. */
+export declare function readHiveopPreviewTable(toml: string): Record<string, string>;
+/** The Procfile `web:` command, or null. */
+export declare function procfileWeb(procfile: string): string | null;
+/**
+ * Decide what a deploy runs. package.json → the Node path exactly as before
+ * (it wins even when Python files sit beside it). Otherwise a Python project
+ * → uv. Otherwise `no_package_json`. Pure: the checkout is read via `files`.
+ */
+export declare function planPreview(files: PreviewCheckoutFiles, mode: PreviewMode, ctx: PreviewPlanContext): PreviewPlanResult;
+/** An installed uv: PATH first, then ~/.local/bin (where ThisOrThat's script puts it), then the tools dir. */
+export declare function findUv(pathEnv: string | undefined, home: string | undefined, toolsDir: string, isExec?: (p: string) => boolean): string | null;
 export declare class PreviewRunner {
     private readonly opts;
     private readonly states;

package/dist/bridge/previewCheckout.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PreviewRunner = exports.LOG_MASK_MIN_VALUE_LENGTH = exports.PREVIEW_PASSTHROUGH_ENV = exports.PREVIEW_BIND_HOST = void 0;
+exports.PreviewRunner = exports.PREVIEW_UV_VERSION = exports.LOG_MASK_MIN_VALUE_LENGTH = exports.PREVIEW_PASSTHROUGH_ENV = exports.PREVIEW_BIND_HOST = void 0;
 exports.maskEnvValues = maskEnvValues;
 exports.buildPreviewEnv = buildPreviewEnv;
 exports.loopbackArgs = loopbackArgs;
@@ -41,6 +41,10 @@ exports.machineExternalAddresses = machineExternalAddresses;
 exports.listensBeyondLoopback = listensBeyondLoopback;
 exports.parseSymrefHead = parseSymrefHead;
 exports.installCommand = installCommand;
+exports.readHiveopPreviewTable = readHiveopPreviewTable;
+exports.procfileWeb = procfileWeb;
+exports.planPreview = planPreview;
+exports.findUv = findUv;
 exports.probeOnce = probeOnce;
 /**
  * tp-05 — Team preview checkout on the owner's HOSTED machine
@@ -102,6 +106,18 @@ exports.probeOnce = probeOnce;
  * machine has. If any of them connects, the new version is killed and the
  * request is refused `unsupported_bind` — never served exposed.
  *
+ * ── Python apps (tp-21) ─────────────────────────────────────────────────────
+ * A repo WITH package.json always takes the Node path above, unchanged. With
+ * no package.json, a `pyproject.toml` / `uv.lock` / `requirements.txt` makes
+ * it a Python preview, installed with uv (`uv sync`, or `uv venv` + `uv pip
+ * install -r`, so Debian's missing python3-venv never matters). The start
+ * command is never guessed: `[tool.hiveop.preview] start = "…"` in
+ * pyproject.toml, else a Procfile `web:` line, else `no_start_command`. uv
+ * itself, its cache and any Python it fetches live under
+ * `<previewsBaseDir>/.tools` (the /data volume), the venv in the slot, so a
+ * machine restart redownloads nothing. The system python3 is used unless the
+ * project pins a version it doesn't satisfy (then uv fetches that one).
+ *
  * Local lane: not here at all — see previewFrames.ts (ADR-0014 scopes it out).
  */
 const child_process_1 = require("child_process");
@@ -220,6 +236,125 @@ function runnerFor(files) {
         return 'yarn';
     return 'npm';
 }
+/** The uv release the runner installs when the box has none (pinned: one known installer). */
+exports.PREVIEW_UV_VERSION = '0.13.0';
+/** `[tool.hiveop.preview]` string keys from pyproject.toml text. Only plain `key = "…"` / `key = '…'` lines. */
+function readHiveopPreviewTable(toml) {
+    const out = {};
+    let inTable = false;
+    for (const raw of toml.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith('[')) {
+            inTable = /^\[\s*tool\s*\.\s*hiveop\s*\.\s*preview\s*\]\s*(#.*)?$/.test(line);
+            continue;
+        }
+        if (!inTable)
+            continue;
+        const m = line.match(/^([A-Za-z0-9_-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')\s*(#.*)?$/);
+        if (!m)
+            continue;
+        out[m[1]] = m[2] !== undefined ? m[2].replace(/\\(["\\])/g, '$1') : m[3];
+    }
+    return out;
+}
+/** The Procfile `web:` command, or null. */
+function procfileWeb(procfile) {
+    for (const line of procfile.split(/\r?\n/)) {
+        const m = line.match(/^web\s*:\s*(.+?)\s*$/);
+        if (m && m[1])
+            return m[1];
+    }
+    return null;
+}
+/**
+ * Decide what a deploy runs. package.json → the Node path exactly as before
+ * (it wins even when Python files sit beside it). Otherwise a Python project
+ * → uv. Otherwise `no_package_json`. Pure: the checkout is read via `files`.
+ */
+function planPreview(files, mode, ctx) {
+    if (files.has('package.json')) {
+        const scripts = parseScripts(files.read('package.json'));
+        const runScript = mode === 'dev' ? 'dev' : 'start';
+        if (!scripts[runScript]) {
+            return { ok: false, reason: 'no_start_script', message: `No "${runScript}" script in package.json.` };
+        }
+        const has = (n) => files.has(n);
+        const steps = [installCommand(has)];
+        if (mode === 'built' && scripts.build)
+            steps.push([runnerFor(has), ['run', 'build']]);
+        return { ok: true, plan: { kind: 'node', steps, start: [runnerFor(has), runArgs(runScript, scripts[runScript])], env: {} } };
+    }
+    const pyproject = files.read('pyproject.toml');
+    const hasUvLock = files.has('uv.lock');
+    const hasRequirements = files.has('requirements.txt');
+    if (pyproject === null && !hasUvLock && !hasRequirements) {
+        return { ok: false, reason: 'no_package_json', message: 'No package.json or Python project on the default branch.' };
+    }
+    const table = pyproject ? readHiveopPreviewTable(pyproject) : {};
+    const procfile = files.read('Procfile');
+    const startCmd = table.start || (procfile ? procfileWeb(procfile) : null);
+    if (!startCmd) {
+        return {
+            ok: false,
+            reason: 'no_start_command',
+            message: 'No start command: add [tool.hiveop.preview] start to pyproject.toml, or a Procfile web: line.',
+        };
+    }
+    const venv = path.join(ctx.slotDir, '.venv');
+    const binDir = path.join(ctx.toolsDir, 'bin');
+    const uv = ctx.uv ?? path.join(binDir, 'uv');
+    const steps = [];
+    if (!ctx.uv) {
+        steps.push(['sh', ['-c',
+                `curl -LsSf https://astral.sh/uv/${exports.PREVIEW_UV_VERSION}/install.sh | env UV_INSTALL_DIR="${binDir}" UV_NO_MODIFY_PATH=1 sh`]]);
+    }
+    const isUvProject = hasUvLock || (pyproject !== null && /^\s*\[project\]\s*(#.*)?$/m.test(pyproject)) || !hasRequirements;
+    if (isUvProject) {
+        steps.push([uv, ['sync', ...(hasUvLock ? ['--frozen'] : []), '--no-dev']]);
+    }
+    else {
+        steps.push([uv, ['venv', '--allow-existing', venv]]);
+        steps.push([uv, ['pip', 'install', '-r', 'requirements.txt']]);
+    }
+    if (mode === 'built' && table.build)
+        steps.push(['sh', ['-c', table.build]]);
+    const basePath = ctx.basePath ?? '';
+    return {
+        ok: true,
+        plan: {
+            kind: 'python',
+            steps,
+            start: ['sh', ['-c', startCmd]],
+            env: {
+                PATH: [path.join(venv, 'bin'), binDir, basePath].filter(Boolean).join(path.delimiter),
+                VIRTUAL_ENV: venv,
+                UV_PROJECT_ENVIRONMENT: venv,
+                UV_CACHE_DIR: path.join(ctx.toolsDir, 'uv-cache'),
+                UV_PYTHON_INSTALL_DIR: path.join(ctx.toolsDir, 'python'),
+                UV_PYTHON_PREFERENCE: 'system',
+                PYTHONUNBUFFERED: '1',
+            },
+        },
+    };
+}
+/** An installed uv: PATH first, then ~/.local/bin (where ThisOrThat's script puts it), then the tools dir. */
+function findUv(pathEnv, home, toolsDir, isExec = isExecutable) {
+    const candidates = [
+        ...(pathEnv ?? '').split(path.delimiter).filter(Boolean).map((d) => path.join(d, 'uv')),
+        ...(home ? [path.join(home, '.local', 'bin', 'uv')] : []),
+        path.join(toolsDir, 'bin', 'uv'),
+    ];
+    return candidates.find(isExec) ?? null;
+}
+function isExecutable(p) {
+    try {
+        fs.accessSync(p, fs.constants.X_OK);
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 class PreviewRunner {
     opts;
     states = new Map();
@@ -239,6 +374,7 @@ class PreviewRunner {
             stepTimeoutMs: opts.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS,
             killGraceMs: opts.killGraceMs ?? 5_000,
             externalAddresses: opts.externalAddresses ?? machineExternalAddresses,
+            toolsDir: opts.toolsDir ?? path.join(opts.previewsBaseDir, '.tools'),
         };
     }
     /** Bring the preview up. Already serving this workspace in this mode → answered as-is. */
@@ -437,29 +573,38 @@ class PreviewRunner {
             this.states.set(workspaceId, { ...prev, status: 'running' });
             return this.snapshot(workspaceId, { sha });
         }
-        const has = (name) => fs.existsSync(path.join(slotDir, name));
-        if (!has('package.json')) {
-            this.states.set(workspaceId, { ...prev, status: serving ? 'running' : 'failed' });
-            return this.withServing(workspaceId, { status: 'failed', reason: 'no_package_json', mode, sha, message: 'No package.json on the default branch.' });
-        }
-        const scripts = readScripts(path.join(slotDir, 'package.json'));
-        const runScript = mode === 'dev' ? 'dev' : 'start';
-        if (!scripts[runScript]) {
+        const files = {
+            has: (name) => fs.existsSync(path.join(slotDir, name)),
+            read: (name) => { try {
+                return fs.readFileSync(path.join(slotDir, name), 'utf8');
+            }
+            catch {
+                return null;
+            } },
+        };
+        const planned = planPreview(files, mode, {
+            slotDir,
+            toolsDir: this.opts.toolsDir,
+            uv: findUv(this.opts.baseEnv.PATH, this.opts.baseEnv.HOME, this.opts.toolsDir),
+            basePath: this.opts.baseEnv.PATH,
+        });
+        if (!planned.ok) {
             this.states.set(workspaceId, { ...prev, status: serving ? 'running' : 'failed' });
-            return this.withServing(workspaceId, {
-                status: 'failed', reason: 'no_start_script', mode, sha,
-                message: `No "${runScript}" script in package.json.`,
-            });
+            return this.withServing(workspaceId, { status: 'failed', reason: planned.reason, mode, sha, message: planned.message });
         }
+        const { plan } = planned;
+        if (plan.kind === 'python')
+            fs.mkdirSync(this.opts.toolsDir, { recursive: true });
         const repoEnv = (0, repoEnv_1.loadRepoEnv)(this.opts.workingCopyDir(workspaceId));
         this.deployedEnvValues.set(workspaceId, Object.values(repoEnv));
-        const env = buildPreviewEnv(this.opts.baseEnv, repoEnv, this.opts.port);
+        const env = { ...buildPreviewEnv(this.opts.baseEnv, repoEnv, this.opts.port), ...plan.env };
         // 2. Install, then (built) build — beside whatever is serving.
-        const [installCmd, installArgs] = installCommand(has);
-        const installed = await this.runStep(installCmd, installArgs, slotDir, env, logFile);
-        let built = installed.ok;
-        if (built && mode === 'built' && scripts.build) {
-            built = (await this.runStep(runnerFor(has), ['run', 'build'], slotDir, env, logFile)).ok;
+        let built = true;
+        for (const [cmd, args] of plan.steps) {
+            if (!(await this.runStep(cmd, args, slotDir, env, logFile)).ok) {
+                built = false;
+                break;
+            }
         }
         if (!built) {
             this.states.set(workspaceId, { ...prev, status: serving ? 'running' : 'build_failed' });
@@ -476,7 +621,7 @@ class PreviewRunner {
             this.states.set(workspaceId, restored ?? { status: 'failed', mode, builtSha });
             return this.withServing(workspaceId, { status: 'failed', reason: 'port_in_use', mode, sha, builtSha, message: 'The preview port is in use.' });
         }
-        const child = this.spawnServer(runnerFor(has), runArgs(runScript, scripts[runScript]), slotDir, env, logFile, workspaceId, targetSlot, sha);
+        const child = this.spawnServer(plan.start[0], plan.start[1], slotDir, env, logFile, workspaceId, targetSlot, sha);
         const ready = await this.waitReady(child, mode);
         if (ready && (await listensBeyondLoopback(this.opts.port, this.opts.externalAddresses()))) {
             // SECURITY: serving this would hand the owner's app (and keys) to every
@@ -492,7 +637,7 @@ class PreviewRunner {
             });
         }
         if (ready) {
-            this.states.set(workspaceId, { status: 'running', mode, activeSlot: targetSlot, runningSha: sha, builtSha, child });
+            this.states.set(workspaceId, { status: 'running', mode, activeSlot: targetSlot, runningSha: sha, builtSha, child, start: plan.start, startEnv: env });
             return this.snapshot(workspaceId, { sha });
         }
         await this.killChild(child);
@@ -503,15 +648,15 @@ class PreviewRunner {
     }
     /** Bring the previous slot back after a failed swap, if there was one. */
     async restoreSlot(workspaceId, prev, env, logFile) {
-        if (!prev.activeSlot || !prev.runningSha)
+        if (!prev.activeSlot || !prev.runningSha || !prev.start)
             return null;
         const dir = path.join(this.wsDir(workspaceId), prev.activeSlot);
-        const has = (name) => fs.existsSync(path.join(dir, name));
-        const script = prev.mode === 'dev' ? 'dev' : 'start';
+        // The serving version's own start command and env (its slot's venv, not the new one's).
+        const restoreEnv = prev.startEnv ?? env;
         fs.appendFileSync(logFile, `--- restoring ${prev.runningSha.slice(0, 7)} ---\n`);
-        const child = this.spawnServer(runnerFor(has), runArgs(script, readScripts(path.join(dir, 'package.json'))[script] ?? ''), dir, env, logFile, workspaceId, prev.activeSlot, prev.runningSha);
+        const child = this.spawnServer(prev.start[0], prev.start[1], dir, restoreEnv, logFile, workspaceId, prev.activeSlot, prev.runningSha);
         if (await this.waitReady(child, prev.mode) && !(await listensBeyondLoopback(this.opts.port, this.opts.externalAddresses()))) {
-            return { status: 'running', mode: prev.mode, activeSlot: prev.activeSlot, runningSha: prev.runningSha, builtSha: prev.builtSha, child };
+            return { status: 'running', mode: prev.mode, activeSlot: prev.activeSlot, runningSha: prev.runningSha, builtSha: prev.builtSha, child, start: prev.start, startEnv: restoreEnv };
         }
         await this.killChild(child);
         this.clearPidfile(workspaceId);
@@ -550,7 +695,8 @@ class PreviewRunner {
             await git(['-C', slotDir, 'reset', '--hard', `refs/remotes/origin/${branch}`]);
             // Untracked leftovers go; ignored ones (node_modules, build output) stay
             // so an unchanged dependency set doesn't reinstall from scratch.
-            await git(['-C', slotDir, 'clean', '-ffd']);
+            // `.venv` is kept even when the repo doesn't ignore it (tp-21).
+            await git(['-C', slotDir, 'clean', '-ffd', '-e', '.venv']);
             const sha = (await git(['-C', slotDir, 'rev-parse', 'HEAD'])).trim();
             fs.appendFileSync(logFile, `default branch ${branch} @ ${sha.slice(0, 12)}\n`);
             return /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
@@ -671,9 +817,9 @@ function runArgs(script, scriptCommand) {
     const extra = loopbackArgs(scriptCommand);
     return extra.length ? ['run', script, '--', ...extra] : ['run', script];
 }
-function readScripts(pkgPath) {
+function parseScripts(pkgText) {
     try {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        const pkg = JSON.parse(pkgText ?? '');
         return pkg && typeof pkg.scripts === 'object' && pkg.scripts ? pkg.scripts : {};
     }
     catch {

package/dist/bridge/storageQuotaFetch.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchStorageQuotaFact = fetchStorageQuotaFact;
+function optString(v) {
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
 function isFiniteNumber(v) {
     return typeof v === 'number' && Number.isFinite(v);
 }
@@ -25,6 +28,8 @@ async function fetchStorageQuotaFact(opts) {
                 additionalGb: opts.additionalGb,
                 suggestedTier: null,
                 suggestedCapGb: null,
+                tierName: optString(b.tierName),
+                suggestedTierName: null,
             };
         }
         if (res.status === 409) {
@@ -42,6 +47,8 @@ async function fetchStorageQuotaFact(opts) {
                     additionalGb: err.additionalGb,
                     suggestedTier: typeof err.suggestedTier === 'string' ? err.suggestedTier : null,
                     suggestedCapGb: isFiniteNumber(err.suggestedCapGb) ? err.suggestedCapGb : null,
+                    tierName: optString(err.tierName),
+                    suggestedTierName: optString(err.suggestedTierName),
                 };
             }
         }

package/dist/bridge/storageQuotaPreflight.d.ts

@@ -64,7 +64,14 @@ export interface StorageQuotaFact {
      *  when `allowed` is false. */
     suggestedTier: string | null;
     suggestedCapGb: number | null;
+    /** The backend's user-facing plan names ("Pay-as-you-go", "Pro", …).
+     *  Absent from an older backend — the raw id is the fallback. */
+    tierName?: string | null;
+    suggestedTierName?: string | null;
 }
+/** "about 4.0 GB", or "under 0.1 GB" for a positive sliver — never a raw
+ *  float, never "about 0.0 GB" for something real. */
+export declare function aboutGb(gb: number): string;
 export type StorageQuotaPreflightVerdict = {
     kind: 'within-quota';
 } | {

package/dist/bridge/storageQuotaPreflight.js

@@ -48,11 +48,19 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLONE_QUOTA_PREFLIGHT_REFUSED = void 0;
+exports.aboutGb = aboutGb;
 exports.checkStorageQuotaPreflight = checkStorageQuotaPreflight;
 exports.storageQuotaPreflightMessage = storageQuotaPreflightMessage;
 /** Frame-level discriminator so a pane can render this refusal distinctly
  *  from CLONE_SPACE_PREFLIGHT_REFUSED — never the same string, on purpose. */
 exports.CLONE_QUOTA_PREFLIGHT_REFUSED = 'CLONE_QUOTA_PREFLIGHT_REFUSED';
+/** "about 4.0 GB", or "under 0.1 GB" for a positive sliver — never a raw
+ *  float, never "about 0.0 GB" for something real. */
+function aboutGb(gb) {
+    if (gb > 0 && gb < 0.1)
+        return 'under 0.1 GB';
+    return `about ${gb.toFixed(1)} GB`;
+}
 /**
  * `fact` of `null` means UNKNOWN (see module doc) — returns `null`, meaning
  * "no verdict, proceed exactly as before this preflight existed". A
@@ -76,10 +84,10 @@ function storageQuotaPreflightMessage(verdict) {
     if (!verdict || verdict.kind === 'within-quota')
         return null;
     const { fact } = verdict;
-    const usage = `Your ${fact.tier} plan allows ${fact.capGb} GB — you're already using about ${fact.usedGb} GB ` +
-        `and this clone needs about ${fact.additionalGb} GB more.`;
+    const usage = `Your ${fact.tierName || fact.tier} plan allows ${fact.capGb} GB — you're already using ${aboutGb(fact.usedGb)} ` +
+        `and this clone needs ${aboutGb(fact.additionalGb)} more.`;
     if (fact.suggestedTier && fact.suggestedCapGb !== null) {
-        return `${usage} Upgrade to ${fact.suggestedTier} (${fact.suggestedCapGb} GB) to fit it.`;
+        return `${usage} Upgrade to ${fact.suggestedTierName || fact.suggestedTier} (${fact.suggestedCapGb} GB) to fit it.`;
     }
     return `${usage} No plan on the current ladder holds this much — contact support about additional storage.`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenrwa/marketplace-cli",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "description": "CLI tool for the Wenrwa Agent Marketplace — monitor bounties, agents, workspaces, and treasury from your terminal",
   "author": "Wenrwa <dev@wenrwa.com>",
   "license": "MIT",