orizu 0.3.2 → 0.3.4

package/README.md

@@ -101,6 +101,17 @@ orizu logout
     <td>Create a project</td>
     <td><code>orizu projects create --name "Support QA" --team ops-eval</code></td>
   </tr>
+  <tr>
+    <td colspan="2"><strong>Prompts</strong></td>
+  </tr>
+  <tr>
+    <td>List prompts</td>
+    <td><code>orizu prompts list --project ops-eval/support-qa</code></td>
+  </tr>
+  <tr>
+    <td>Show prompt comments</td>
+    <td><code>orizu prompts comments &lt;promptIdOrName&gt; --project ops-eval/support-qa</code></td>
+  </tr>
   <tr>
     <td colspan="2"><strong>Datasets</strong></td>
   </tr>
@@ -162,6 +173,10 @@ orizu logout
     <td>Link a dataset to an app</td>
     <td><code>orizu apps link-dataset --app &lt;appId&gt; --dataset &lt;datasetId&gt;</code></td>
   </tr>
+  <tr>
+    <td>Export app source</td>
+    <td><code>orizu apps export --app &lt;appId&gt; --project ops-eval/support-qa --out ./apps/SupportLabeler.tsx</code></td>
+  </tr>
   <tr>
     <td colspan="2"><strong>Tasks</strong></td>
   </tr>

package/dist/index.js

@@ -16,6 +16,7 @@ import { parseDatasetReference } from './dataset-download.js';
 import { parseGlobalFlags } from './global-flags.js';
 import { assertSecureTokenTransport, authedFetch, getBaseUrl, resolveLoginBaseUrl, setGlobalFlags, } from './http.js';
 import { formatTaskCreateError } from './task-create-error.js';
+const MAX_README_LENGTH = 200_000;
 function getCliVersion() {
     const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
     if (typeof packageJson.version !== 'string' || packageJson.version.length === 0) {
@@ -30,10 +31,10 @@ function printVersion() {
     printLine(`orizu ${getCliVersion()}`);
 }
 function printUsage() {
-    printLine(`orizu global options:\n\n  --local                 Use http://localhost:3000\n  --server <url>          Use a specific server origin (for example: https://preview.example.com)\n  --version, -v           Print the orizu CLI version\n\norizu commands:\n\n  orizu login [--no-prompt-if-logged-in]\n  orizu logout\n  orizu whoami\n  orizu env [--project <team/project>] [--project-id <projectId>]\n  orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json\n  orizu teams list\n  orizu teams create [--name <name>]\n  orizu teams members list [--team <teamSlug>]\n  orizu teams members add --email <email> [--team <teamSlug>]\n  orizu teams members remove --email <email> [--team <teamSlug>]\n  orizu teams members role --team <teamSlug> --email <email> --role <admin|member>\n  orizu projects list [--team <teamSlug>]\n  orizu projects create --name <name> [--team <teamSlug>]\n  orizu prompts list --project <team/project>\n  orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu prompts labels set <prompt-name> <label> --version <version-id> [--project <team/project>] [--json]\n  orizu prompts scorers set-headline <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu prompts scorers add <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu scorers list --project <team/project>\n  orizu scorers register --project <team/project> --name <name> --manifest <manifest.json> [--prompt-version <id>] [--runner-version <id>] [--label <label>] [--json]\n  orizu scorers detail <scorer-id-or-name> --project <team/project> [--json]\n  orizu scorers labels set <scorer-name> <label> --version <scorer-version-id> [--project <team/project>] [--json]\n  orizu scores submit <results.jsonl|results.json> --scorer-version <id> --subject-version <prompt-version-id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu judges list --project <team/project>\n  orizu judges pull <judge-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu runners push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>\n  orizu optimizers push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]\n  orizu apps list [--project <team/project>]\n  orizu apps create --project <team/project> --name <name> --dataset <datasetId> --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps update [--app <appId>] [--project <team/project>] --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps link-dataset --dataset <datasetId> [--app <appId>] [--project <team/project>] [--version <n>]\n  orizu apps detail --app <appId> [--project <team/project>] [--json]\n  orizu tasks list [--project <team/project>]\n  orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]\n  orizu tasks assign --task <taskId> --assignees <userId1,userId2>\n  orizu tasks status --task <taskId> [--json]\n  orizu tasks pause --task <taskId>\n  orizu tasks unpause --task <taskId>\n  orizu datasets upload --file <path> [--project <team/project>] [--name <name>]\n  orizu datasets push <path> [--project <team/project>] [--name <name>] [--json]\n  orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--json]\n  orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]\n  orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]\n  orizu datasets append [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets edit-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets delete-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --row-ids <id1,id2>\n  orizu datasets delete [--dataset <datasetId|datasetUrl>] [--project <team/project>]\n  orizu datasets lock [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--reason <text>]\n  orizu datasets clone [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--name <name>]\n  orizu tasks export [--task <taskId>] [--format <csv|json|jsonl>] [--out <path>]`);
+    printLine(`orizu global options:\n\n  --local                 Use http://localhost:3000\n  --server <url>          Use a specific server origin (for example: https://preview.example.com)\n  --version, -v           Print the orizu CLI version\n\norizu commands:\n\n  orizu login [--no-prompt-if-logged-in]\n  orizu logout\n  orizu whoami\n  orizu env [--project <team/project>] [--project-id <projectId>]\n  orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json\n  orizu teams list\n  orizu teams create [--name <name>]\n  orizu teams members list [--team <teamSlug>]\n  orizu teams members add --email <email> [--team <teamSlug>]\n  orizu teams members remove --email <email> [--team <teamSlug>]\n  orizu teams members role --team <teamSlug> --email <email> --role <admin|member>\n  orizu projects list [--team <teamSlug>]\n  orizu projects create --name <name> [--team <teamSlug>]\n  orizu prompts list --project <team/project>\n  orizu prompts comments <prompt-id-or-name> --project <team/project> [--label <label> | --version <id>] [--json]\n  orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu prompts labels set <prompt-name> <label> --version <version-id> [--project <team/project>] [--json]\n  orizu prompts scorers set-headline <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu prompts scorers add <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu scorers list --project <team/project>\n  orizu scorers register --project <team/project> --name <name> --manifest <manifest.json> [--prompt-version <id>] [--runner-version <id>] [--label <label>] [--json]\n  orizu scorers detail <scorer-id-or-name> --project <team/project> [--json]\n  orizu scorers labels set <scorer-name> <label> --version <scorer-version-id> [--project <team/project>] [--json]\n  orizu scores submit <results.jsonl|results.json> --scorer-version <id> --subject-version <prompt-version-id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu judges list --project <team/project>\n  orizu judges pull <judge-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu runners push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>\n  orizu optimizers push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]\n  orizu apps list [--project <team/project>]\n  orizu apps create --project <team/project> --name <name> --dataset <datasetId> --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps update [--app <appId>] [--project <team/project>] --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps link-dataset --dataset <datasetId> [--app <appId>] [--project <team/project>] [--version <n>]\n  orizu apps detail --app <appId> [--project <team/project>] [--json]\n  orizu apps export [--app <appId>] [--project <team/project>] [--version <n>] [--out <path>]\n  orizu tasks list [--project <team/project>]\n  orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]\n  orizu tasks assign --task <taskId> --assignees <userId1,userId2>\n  orizu tasks status --task <taskId> [--json]\n  orizu tasks pause --task <taskId>\n  orizu tasks unpause --task <taskId>\n  orizu datasets upload --file <path> [--project <team/project>] [--name <name>] [--readme-file <README.md> | --readme-text <markdown>]\n  orizu datasets push <path> [--project <team/project>] [--name <name>] [--readme-file <README.md> | --readme-text <markdown>] [--json]\n  orizu datasets readme set <datasetId|dataset-name> [--project <team/project>] (--readme-file <README.md> | --readme-text <markdown>) [--json]\n  orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--readme-file <README.md> | --readme-text <markdown>] [--json]\n  orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]\n  orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]\n  orizu datasets append [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets edit-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets delete-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --row-ids <id1,id2>\n  orizu datasets delete [--dataset <datasetId|datasetUrl>] [--project <team/project>]\n  orizu datasets lock [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--reason <text>]\n  orizu datasets clone [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--name <name>]\n  orizu tasks export [--task <taskId>] [--format <csv|json|jsonl>] [--out <path>]`);
 }
 function printOptimizationUsage() {
-    printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--json]`);
+    printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--log-dir logs]\n  orizu optimizations export <run-id> [--out <path>] [--json]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--report <markdown|@file> | --report-file <path>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--report <markdown|@file> | --report-file <path>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--report <markdown|@file> | --report-file <path>] [--json]`);
 }
 let cliArgs = process.argv.slice(2);
 function getArg(name) {
@@ -59,6 +60,20 @@ export function expandHomePath(path) {
     }
     return path;
 }
+function readReadmeMarkdownFromArgs(usage) {
+    const readmeFile = getArg('--readme-file');
+    const readmeText = getArg('--readme-text');
+    if (readmeFile !== null && readmeText !== null) {
+        throw new Error(`Use either --readme-file or --readme-text, not both.\n${usage}`);
+    }
+    const markdown = readmeFile !== null
+        ? readFileSync(expandHomePath(readmeFile), 'utf8')
+        : readmeText;
+    if (markdown !== null && markdown.length > MAX_README_LENGTH) {
+        throw new Error(`README markdown is too large. Maximum size is ${MAX_README_LENGTH} characters.`);
+    }
+    return markdown;
+}
 function createCodeVerifier() {
     return randomBytes(32).toString('base64url');
 }
@@ -480,6 +495,63 @@ function printTaskStatusSummary(data) {
         });
     }
 }
+function compactTerminalText(value, maxLength = 160) {
+    const compact = sanitizeTerminalText(value).replace(/\s+/g, ' ').trim();
+    if (compact.length <= maxLength) {
+        return compact;
+    }
+    return `${compact.slice(0, Math.max(0, maxLength - 1)).trim()}…`;
+}
+function printIndentedBody(value, indent) {
+    const lines = sanitizeTerminalText(value || '').split(/\r?\n/);
+    for (const line of lines) {
+        printLine(`${indent}${line}`);
+    }
+}
+function formatPromptCommentAnchor(anchor) {
+    if (!anchor) {
+        return null;
+    }
+    const lineLabel = anchor.startLine && anchor.endLine
+        ? anchor.startLine === anchor.endLine
+            ? `line ${anchor.startLine}`
+            : `lines ${anchor.startLine}-${anchor.endLine}`
+        : null;
+    const selectedText = anchor.text ? `"${compactTerminalText(anchor.text, 180)}"` : null;
+    if (lineLabel && selectedText) {
+        return `${lineLabel}: ${selectedText}`;
+    }
+    return lineLabel || selectedText;
+}
+function printPromptComments(data) {
+    const versionLabel = data.version.versionLabel || (data.version.versionNumber ? `v${data.version.versionNumber}` : data.version.id);
+    printLine(`Prompt: ${sanitizeTerminalText(data.prompt.name)} (${sanitizeTerminalText(data.prompt.id)})`);
+    printLine(`Version: ${sanitizeTerminalText(String(versionLabel))} (${sanitizeTerminalText(data.version.id)})`);
+    printLine(`Comments: ${data.summary.threadCount} thread${data.summary.threadCount === 1 ? '' : 's'} ` +
+        `(${data.summary.openThreadCount} open, ${data.summary.resolvedThreadCount} resolved, ${data.summary.replyCount} replies)`);
+    if (data.comments.length === 0) {
+        printLine('\nNo comments found for this prompt version.');
+        return;
+    }
+    for (const [index, thread] of data.comments.entries()) {
+        const authorName = thread.author?.name || 'Unknown';
+        const anchor = formatPromptCommentAnchor(thread.anchor);
+        printLine('');
+        printLine(`${index + 1}. [${thread.status}] ${sanitizeTerminalText(authorName)} · ${sanitizeTerminalText(thread.createdAt)}`);
+        if (anchor) {
+            printLine(`   Selection: ${anchor}`);
+        }
+        printIndentedBody(thread.body, '   ');
+        if (thread.replies.length > 0) {
+            printLine(`   Replies (${thread.replies.length})`);
+            for (const reply of thread.replies) {
+                const replyAuthor = reply.author?.name || 'Unknown';
+                printLine(`   - ${sanitizeTerminalText(replyAuthor)} · ${sanitizeTerminalText(reply.createdAt)}`);
+                printIndentedBody(reply.body, '     ');
+            }
+        }
+    }
+}
 const DEFAULT_AUTH_CALLBACK_PORT = 43123;
 function resolveAuthCallbackPort() {
     const envPort = process.env.ORIZU_AUTH_PORT;
@@ -788,6 +860,33 @@ async function listJudges() {
     const data = await parseJsonResponse(response, 'Judges list');
     printPromptSummaries(data.judges, 'No judges found.');
 }
+async function listPromptComments() {
+    const promptRef = getPositionalArg(2);
+    const project = getArg('--project') || await resolveProjectSlug(null);
+    const label = getArg('--label');
+    const version = getArg('--version');
+    if (!promptRef) {
+        throw new Error('Usage: orizu prompts comments <prompt-id-or-name> --project <team/project> [--label <label> | --version <version-id>] [--json]');
+    }
+    if (label && version) {
+        throw new Error('Use either --label or --version, not both');
+    }
+    const params = new URLSearchParams({ project });
+    if (label)
+        params.set('label', label);
+    if (version)
+        params.set('version', version);
+    const response = await authedFetch(`/api/cli/prompts/${encodeURIComponent(promptRef)}/comments?${params.toString()}`);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch prompt comments: ${await response.text()}`);
+    }
+    const data = await parseJsonResponse(response, 'Prompt comments');
+    if (hasJsonFlag()) {
+        printJson(data);
+        return;
+    }
+    printPromptComments(data);
+}
 async function listScorers() {
     const project = getArg('--project') || await resolveProjectSlug(null);
     const response = await authedFetch(`/api/cli/scorers?project=${encodeURIComponent(project)}`);
@@ -1160,14 +1259,19 @@ async function createDatasetVersion() {
     const datasetId = getPositionalArg(3) || getArg('--dataset');
     const versionLabel = getArg('--label') || getArg('--version-label') || null;
     const project = getArg('--project');
+    const usage = 'Usage: orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--readme-file <README.md> | --readme-text <markdown>] [--json]';
     if (!datasetId) {
-        throw new Error('Usage: orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--json]');
+        throw new Error(usage);
     }
+    const readmeMarkdown = readReadmeMarkdownFromArgs(usage);
     const resolvedDatasetId = await resolveDatasetIdForProject(datasetId, project);
     const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(resolvedDatasetId)}/versions`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ versionLabel }),
+        body: JSON.stringify({
+            versionLabel,
+            ...(readmeMarkdown !== null ? { readmeMarkdown } : {}),
+        }),
     });
     if (!response.ok) {
         throw new Error(`Failed to create dataset version: ${await response.text()}`);
@@ -1329,6 +1433,7 @@ function normalizeScoreResultsInput(sourcePath, raw) {
         throw new Error(`Invalid score results JSON '${sourcePath}': ${message}`);
     }
 }
+const OPTIMIZATION_REPORT_MAX_BYTES = 2 * 1024 * 1024;
 function parseOptionalNumberFlag(name) {
     const value = getArg(name);
     if (!value) {
@@ -1343,6 +1448,40 @@ function parseOptionalNumberFlag(name) {
 function hasObjectKeys(value) {
     return Object.keys(value).length > 0;
 }
+function readOptimizationReportInput() {
+    const report = getArg('--report');
+    const reportFile = getArg('--report-file');
+    if (report && reportFile) {
+        throw new Error('Use either --report or --report-file, not both');
+    }
+    if (!report && !reportFile) {
+        return null;
+    }
+    let markdown;
+    let sourceName;
+    if (reportFile) {
+        const expandedPath = expandHomePath(reportFile);
+        markdown = readSourceFile(reportFile);
+        sourceName = basename(expandedPath);
+    }
+    else if (report?.startsWith('@')) {
+        const path = report.slice(1);
+        const expandedPath = expandHomePath(path);
+        markdown = readSourceFile(path);
+        sourceName = basename(expandedPath);
+    }
+    else {
+        markdown = report || '';
+        sourceName = 'inline';
+    }
+    if (!markdown.trim()) {
+        throw new Error('Optimization report markdown must not be blank');
+    }
+    if (Buffer.byteLength(markdown, 'utf8') > OPTIMIZATION_REPORT_MAX_BYTES) {
+        throw new Error(`Optimization report exceeds ${OPTIMIZATION_REPORT_MAX_BYTES} bytes`);
+    }
+    return { markdown, sourceName };
+}
 async function startOptimizationRun() {
     const project = getArg('--project') || await resolveProjectSlug(null);
     const optimizerVersionId = getArg('--optimizer-version');
@@ -1419,6 +1558,10 @@ async function updateOptimizationRunLifecycle(action) {
     };
     const metadata = readJsonObjectArg(getArg('--metadata'), 'optimization metadata');
     const reason = getArg('--reason');
+    const report = readOptimizationReportInput();
+    if (report && (action === 'pause' || action === 'resume')) {
+        throw new Error(`orizu optimizations ${action} does not accept optimization reports`);
+    }
     if ((action === 'pause' || action === 'cancel') && reason) {
         metadata.reason = reason;
     }
@@ -1429,6 +1572,10 @@ async function updateOptimizationRunLifecycle(action) {
     if (hasObjectKeys(metadata)) {
         body.metadata = metadata;
     }
+    if (report) {
+        body.reportMarkdown = report.markdown;
+        body.reportSourceName = report.sourceName;
+    }
     if (action === 'finish') {
         const bestScore = parseOptionalNumberFlag('--best-score');
         if (bestScore !== undefined) {
@@ -1473,6 +1620,27 @@ async function updateOptimizationRunLifecycle(action) {
         printLine(`Cancelled optimization run ${id}`);
     }
 }
+async function exportOptimizationRun() {
+    const runId = getPositionalArg(2) || getArg('--run-id');
+    const outPathArg = getArg('--out');
+    if (!runId) {
+        throw new Error('Usage: orizu optimizations export <run-id> [--out <path>] [--json]');
+    }
+    const response = await authedFetch(`/api/cli/optimization-runs/${encodeURIComponent(runId)}/export`);
+    if (!response.ok) {
+        throw new Error(`Failed to export optimization run: ${await response.text()}`);
+    }
+    const data = await parseJsonResponse(response, 'Optimization export');
+    if (hasJsonFlag() && !outPathArg) {
+        printJson(data);
+        return;
+    }
+    const filename = outPathArg
+        ? expandHomePath(outPathArg)
+        : `${runId}.optimization.json`;
+    writeTextFileEnsuringDir(filename, `${JSON.stringify(data, null, 2)}\n`);
+    printLine(`Saved optimization export to ${sanitizeTerminalText(filename)}`);
+}
 function removeFlagWithValue(args, flag) {
     const filtered = [];
     for (let index = 0; index < args.length; index += 1) {
@@ -2080,6 +2248,14 @@ async function updateTaskStatus(targetStatus) {
     const action = targetStatus === 'paused' ? 'Paused' : 'Unpaused';
     printLine(`${action} task ${sanitizeTerminalText(data.task.id)} [${sanitizeTerminalText(data.task.status)}]`);
 }
+function defaultAppExportFilename(appName, versionNum) {
+    const safeName = appName
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 100);
+    return `${safeName || 'app'}.v${versionNum}.tsx`;
+}
 async function appDetail() {
     const appId = getArg('--app');
     const project = getArg('--project');
@@ -2118,6 +2294,40 @@ async function appDetail() {
     printLine(`  Created: ${sanitizeTerminalText(detail.createdAt)}`);
     printLine(`  Updated: ${sanitizeTerminalText(detail.updatedAt)}`);
 }
+async function exportAppSource() {
+    const project = getArg('--project');
+    const versionArg = getArg('--version');
+    const outPathArg = getArg('--out');
+    let appId = getArg('--app');
+    const versionNum = versionArg && /^[1-9]\d*$/.test(versionArg)
+        ? Number.parseInt(versionArg, 10)
+        : undefined;
+    if (versionArg && versionNum === undefined) {
+        throw new Error('--version must be a positive integer');
+    }
+    if (!appId) {
+        const selected = await selectAppIdInteractively(project);
+        appId = selected.appId;
+    }
+    const query = new URLSearchParams();
+    if (project) {
+        query.set('project', project);
+    }
+    if (versionNum) {
+        query.set('version', String(versionNum));
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : '';
+    const response = await authedFetch(`/api/cli/apps/${encodeURIComponent(appId)}/export${suffix}`);
+    if (!response.ok) {
+        throw new Error(`Failed to export app (${response.status}): ${await response.text()}`);
+    }
+    const data = await parseJsonResponse(response, 'App export');
+    const filename = outPathArg
+        ? expandHomePath(outPathArg)
+        : defaultAppExportFilename(data.app.name, data.version.versionNum);
+    writeTextFileEnsuringDir(filename, data.version.code);
+    printLine(`Saved app ${sanitizeTerminalText(data.app.name)} v${data.version.versionNum} source to ${sanitizeTerminalText(filename)}`);
+}
 async function listTeamMembers() {
     const teamSlug = await resolveTeamSlug(getArg('--team'));
     printTeamMembers(await fetchTeamMembers(teamSlug));
@@ -2182,7 +2392,7 @@ async function changeTeamMemberRole() {
     }
     printLine(`Updated ${sanitizeTerminalText(member.email)} role to ${sanitizeTerminalText(role)}`);
 }
-async function createDatasetFromRows(project, name, sourceType, rows) {
+async function createDatasetFromRows(project, name, sourceType, rows, readmeMarkdown = null) {
     const response = await authedFetch('/api/cli/datasets/upload', {
         method: 'POST',
         headers: {
@@ -2193,6 +2403,7 @@ async function createDatasetFromRows(project, name, sourceType, rows) {
             name,
             rows,
             sourceType,
+            ...(readmeMarkdown !== null ? { readmeMarkdown } : {}),
         }),
     });
     if (!response.ok) {
@@ -2201,7 +2412,7 @@ async function createDatasetFromRows(project, name, sourceType, rows) {
     }
     return parseJsonResponse(response, 'Dataset upload');
 }
-async function uploadJsonlDatasetInChunks(file, project, datasetName) {
+async function uploadJsonlDatasetInChunks(file, project, datasetName, readmeMarkdown = null) {
     let dataset = null;
     let totalUploaded = 0;
     let chunkIndex = 0;
@@ -2229,7 +2440,7 @@ async function uploadJsonlDatasetInChunks(file, project, datasetName) {
         printLine(`Uploading chunk ${chunkIndex} (${chunk.length} rows)...`);
         try {
             if (!dataset) {
-                const data = await createDatasetFromRows(project, datasetName, 'jsonl', chunk);
+                const data = await createDatasetFromRows(project, datasetName, 'jsonl', chunk, readmeMarkdown);
                 dataset = data.dataset;
                 totalUploaded = data.dataset.rowCount;
                 continue;
@@ -2264,18 +2475,20 @@ async function uploadDataset() {
     const projectArg = getArg('--project');
     const fileArg = getArg('--file');
     const name = getArg('--name');
+    const usage = 'Usage: orizu datasets upload --file <path> [--project <team/project>] [--name <name>] [--readme-file <README.md> | --readme-text <markdown>]';
     if (!fileArg) {
-        throw new Error('Usage: orizu datasets upload --file <path> [--project <team/project>] [--name <name>]');
+        throw new Error(usage);
     }
+    const readmeMarkdown = readReadmeMarkdownFromArgs(usage);
     const file = expandHomePath(fileArg);
     const project = await resolveProjectSlug(projectArg);
     const datasetName = name || basename(file);
     if (extname(file).toLowerCase() === '.jsonl') {
-        await uploadJsonlDatasetInChunks(file, project, datasetName);
+        await uploadJsonlDatasetInChunks(file, project, datasetName, readmeMarkdown);
         return;
     }
     const { rows, sourceType } = parseDatasetFile(file);
-    const data = await createDatasetFromRows(project, datasetName, sourceType, rows);
+    const data = await createDatasetFromRows(project, datasetName, sourceType, rows, readmeMarkdown);
     printLine(`Uploaded dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}) with ${data.dataset.rowCount} rows.`);
     if (data.dataset.url) {
         printLine(`View dataset: ${formatTerminalLink(data.dataset.url)}`);
@@ -2285,20 +2498,26 @@ async function pushDataset() {
     const projectArg = getArg('--project');
     const fileArg = getPositionalArg(2) || getArg('--file');
     const name = getArg('--name');
+    const usage = 'Usage: orizu datasets push <rows.csv|rows.json|rows.jsonl> [--project <team/project>] [--name <name>] [--readme-file <README.md> | --readme-text <markdown>] [--json]';
     if (!fileArg) {
-        throw new Error('Usage: orizu datasets push <rows.csv|rows.json|rows.jsonl> [--project <team/project>] [--name <name>] [--json]');
+        throw new Error(usage);
     }
+    const readmeMarkdown = readReadmeMarkdownFromArgs(usage);
     const file = expandHomePath(fileArg);
     const project = await resolveProjectSlug(projectArg);
     const datasetName = name || basename(file);
     const { rows, sourceType } = parseDatasetFile(file);
-    const data = await createDatasetFromRows(project, datasetName, sourceType, rows);
+    const data = await createDatasetFromRows(project, datasetName, sourceType, rows, readmeMarkdown);
     if (hasJsonFlag()) {
-        printJson({
+        const payload = {
             dataset_id: data.dataset.id,
             name: data.dataset.name,
             row_count: data.dataset.rowCount,
-        });
+        };
+        if (data.readmeVersion?.id) {
+            payload.readme_version_id = data.readmeVersion.id;
+        }
+        printJson(payload);
         return;
     }
     printLine(`Uploaded dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}) with ${data.dataset.rowCount} rows.`);
@@ -2306,6 +2525,38 @@ async function pushDataset() {
         printLine(`View dataset: ${formatTerminalLink(data.dataset.url)}`);
     }
 }
+async function setDatasetReadme() {
+    const datasetId = getPositionalArg(3) || getArg('--dataset');
+    const project = getArg('--project');
+    const usage = 'Usage: orizu datasets readme set <datasetId|dataset-name> [--project <team/project>] (--readme-file <README.md> | --readme-text <markdown>) [--json]';
+    if (!datasetId) {
+        throw new Error(usage);
+    }
+    const readmeMarkdown = readReadmeMarkdownFromArgs(usage);
+    if (readmeMarkdown === null) {
+        throw new Error(usage);
+    }
+    const resolvedDatasetId = await resolveDatasetIdForProject(datasetId, project);
+    const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(resolvedDatasetId)}/readme`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ markdown: readmeMarkdown }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to save dataset README: ${await response.text()}`);
+    }
+    const data = await parseJsonResponse(response, 'Dataset README save');
+    if (hasJsonFlag()) {
+        printJson({
+            dataset_id: data.version.dataset_id,
+            readme_version_id: data.version.id,
+            readme_version_num: data.version.version_num,
+        });
+        return;
+    }
+    printLine(`Saved README v${data.version.version_num} for dataset ` +
+        `${sanitizeTerminalText(data.version.dataset_id)} (${sanitizeTerminalText(data.version.id)}).`);
+}
 function getDatasetReferenceInput() {
     const fromFlag = getArg('--dataset');
     if (fromFlag) {
@@ -2937,6 +3188,10 @@ export async function main(rawArgs = process.argv.slice(2)) {
         await listPrompts();
         return;
     }
+    if (command === 'prompts' && subcommand === 'comments') {
+        await listPromptComments();
+        return;
+    }
     if (command === 'prompts' && subcommand === 'pull') {
         await pullPromptArtifact('prompt');
         return;
@@ -3013,6 +3268,10 @@ export async function main(rawArgs = process.argv.slice(2)) {
         await runGepaOptimization();
         return;
     }
+    if (command === 'optimizations' && subcommand === 'export') {
+        await exportOptimizationRun();
+        return;
+    }
     if (command === 'optimizations' &&
         (subcommand === 'pause' ||
             subcommand === 'resume' ||
@@ -3042,6 +3301,10 @@ export async function main(rawArgs = process.argv.slice(2)) {
         await appDetail();
         return;
     }
+    if (command === 'apps' && subcommand === 'export') {
+        await exportAppSource();
+        return;
+    }
     if (command === 'tasks' && subcommand === 'list') {
         await listTasks();
         return;
@@ -3083,6 +3346,10 @@ export async function main(rawArgs = process.argv.slice(2)) {
         return;
     }
     const datasetsAction = cliArgs[2];
+    if (command === 'datasets' && subcommand === 'readme' && datasetsAction === 'set') {
+        await setDatasetReadme();
+        return;
+    }
     if (command === 'datasets' && subcommand === 'versions' && datasetsAction === 'create') {
         await createDatasetVersion();
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orizu",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "private": false,
   "type": "module",
   "bin": {