orizu 0.3.7 → 0.4.1

package/src/csv.ts

@@ -1,4 +1,124 @@
-export function parseCSV(csvText: string): string[][] {
+/**
+ * CSV parsing utilities with RFC 4180 compliance.
+ *
+ * This is the single canonical implementation shared by the web app and the
+ * published CLI: lib/csv-utils.ts re-exports from here. It lives inside
+ * packages/cli because the CLI is published standalone to npm and cannot
+ * import files outside its package root, while the app can import anything.
+ *
+ * Resource limits are enforced while parsing so a hostile CSV cannot exhaust
+ * memory. The numeric defaults are inlined here (this package cannot import
+ * @/lib/resource-limits) and mirror RESOURCE_LIMITS.CSV_* in that module —
+ * keep the two in sync.
+ */
+
+export class CSVResourceLimitError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CSVResourceLimitError'
+  }
+}
+
+export interface CSVParseOptions {
+  maxBytes?: number
+  maxRows?: number
+  maxFields?: number
+  maxFieldBytes?: number
+}
+
+// Mirrors RESOURCE_LIMITS.CSV_* in lib/resource-limits.ts.
+const DEFAULT_CSV_MAX_BYTES = 10 * 1024 * 1024
+const DEFAULT_CSV_MAX_ROWS = 5_000
+const DEFAULT_CSV_MAX_FIELDS = 200
+const DEFAULT_CSV_MAX_FIELD_BYTES = 128 * 1024
+
+function getUtf8ByteLength(value: string): number {
+  let bytes = 0
+
+  for (let index = 0; index < value.length; index += 1) {
+    const codePoint = value.charCodeAt(index)
+
+    if (codePoint <= 0x7f) {
+      bytes += 1
+    } else if (codePoint <= 0x7ff) {
+      bytes += 2
+    } else if (
+      codePoint >= 0xd800 &&
+      codePoint <= 0xdbff &&
+      index + 1 < value.length
+    ) {
+      const next = value.charCodeAt(index + 1)
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4
+        index += 1
+      } else {
+        bytes += 3
+      }
+    } else {
+      bytes += 3
+    }
+  }
+
+  return bytes
+}
+
+function enforceCsvTextLimit(csvText: string, options: CSVParseOptions): void {
+  const maxBytes = options.maxBytes ?? DEFAULT_CSV_MAX_BYTES
+  if (getUtf8ByteLength(csvText) > maxBytes) {
+    throw new CSVResourceLimitError(`CSV data is too large (max ${maxBytes} bytes)`)
+  }
+}
+
+function enforceRowLimit(rowCount: number, options: CSVParseOptions): void {
+  const maxRows = options.maxRows ?? DEFAULT_CSV_MAX_ROWS
+  if (rowCount > maxRows) {
+    throw new CSVResourceLimitError(`CSV has too many rows (max ${maxRows})`)
+  }
+}
+
+function enforceFieldLimits(row: string[], options: CSVParseOptions): void {
+  const maxFields = options.maxFields ?? DEFAULT_CSV_MAX_FIELDS
+  if (row.length > maxFields) {
+    throw new CSVResourceLimitError(`CSV row has too many fields (max ${maxFields})`)
+  }
+
+  const maxFieldBytes = options.maxFieldBytes ?? DEFAULT_CSV_MAX_FIELD_BYTES
+  for (const field of row) {
+    if (getUtf8ByteLength(field) > maxFieldBytes) {
+      throw new CSVResourceLimitError(`CSV field is too large (max ${maxFieldBytes} bytes)`)
+    }
+  }
+}
+
+function addCsvRow(result: string[][], row: string[], options: CSVParseOptions): void {
+  // Only keep rows with at least one non-whitespace field
+  if (!row.some(field => field.trim())) {
+    return
+  }
+
+  enforceFieldLimits(row, options)
+  result.push(row)
+  enforceRowLimit(result.length, options)
+}
+
+/**
+ * Parses CSV text into a 2D array of strings, handling quoted fields, escaped
+ * quotes, multiline fields, and different line endings (CRLF, LF, CR).
+ * Completely empty rows are skipped.
+ *
+ * Resource limits (size, rows, fields, field size) are enforced during
+ * parsing; pass `options` to override the defaults. A violation throws
+ * {@link CSVResourceLimitError}.
+ *
+ * @example
+ * ```typescript
+ * const csv = 'name,age,city\nJohn,25,"New York"'
+ * parseCSV(csv) // [['name', 'age', 'city'], ['John', '25', 'New York']]
+ * ```
+ */
+export function parseCSV(csvText: string, options: CSVParseOptions = {}): string[][] {
+  enforceCsvTextLimit(csvText, options)
+
   const result: string[][] = []
   let currentRow: string[] = []
   let currentField = ''
@@ -11,6 +131,7 @@ export function parseCSV(csvText: string): string[][] {
 
     if (char === '"') {
       if (inQuotes && nextChar === '"') {
+        // Escaped quote - convert "" to "
         currentField += '"'
         i += 2
         continue
@@ -32,9 +153,7 @@ export function parseCSV(csvText: string): string[][] {
       if (char === '\n' || char === '\r') {
         if (currentField || currentRow.length > 0) {
           currentRow.push(currentField)
-          if (currentRow.some(field => field.trim())) {
-            result.push(currentRow)
-          }
+          addCsvRow(result, currentRow, options)
           currentRow = []
           currentField = ''
         }
@@ -53,18 +172,29 @@ export function parseCSV(csvText: string): string[][] {
     i++
   }
 
+  // CSV might not end with a newline
   if (currentField || currentRow.length > 0) {
     currentRow.push(currentField)
-    if (currentRow.some(field => field.trim())) {
-      result.push(currentRow)
-    }
+    addCsvRow(result, currentRow, options)
   }
 
   return result
 }
 
-export function parseCSVToObjects(csvText: string): Record<string, unknown>[] {
-  const rows = parseCSV(csvText)
+/**
+ * Parses CSV data into an array of objects using the first row as headers.
+ *
+ * @example
+ * ```typescript
+ * const csv = 'name,age\nJohn,25'
+ * parseCSVToObjects(csv) // [{ name: 'John', age: '25' }]
+ * ```
+ */
+export function parseCSVToObjects(
+  csvText: string,
+  options: CSVParseOptions = {}
+): Record<string, string>[] {
+  const rows = parseCSV(csvText, options)
 
   if (rows.length < 2) {
     return []
@@ -74,7 +204,7 @@ export function parseCSVToObjects(csvText: string): Record<string, unknown>[] {
   const dataRows = rows.slice(1)
 
   return dataRows.map(row => {
-    const obj: Record<string, unknown> = {}
+    const obj: Record<string, string> = {}
     headers.forEach((header, index) => {
       obj[header] = row[index]?.trim() || ''
     })

package/src/help.ts

@@ -22,6 +22,7 @@ interface CliGroupDoc {
 }
 
 const GLOBAL_OPTIONS = [
+  ['--json', 'Emit machine-readable JSON instead of human text. Available on every command, as a prefix (orizu --json <command>) or trailing flag.'],
   ['--local', 'Use http://localhost:3000.'],
   ['--server <url>', 'Use a specific server origin, for example https://preview.example.com.'],
   ['--version, -v', 'Print the orizu CLI version.'],
@@ -76,26 +77,111 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'Submit an optimization event payload.',
     group: 'Optimizations',
   },
+  {
+    path: ['setup'],
+    usage: 'orizu setup [--agent <claude|codex>]... [--scope global|project] [--mode auto|link|copy] [--workspace|--no-workspace] [--no-install] [--no-handoff] [--launch <claude|codex>] [--skip-login] [--yes] [--dry-run] [--no-input] [--json]',
+    summary: 'Guided onboarding: sign in, set up your coding agents, create a local workspace, and hand off to your agent.',
+    group: 'Agent setup',
+    options: [
+      { name: '--agent <agent>', help: 'Coding agent to set up. Repeat for multiple agents.', repeatable: true, choices: ['claude', 'codex'] },
+      { name: '--scope <scope>', help: 'global (default) installs for you across all projects; project installs into the current repo.', choices: ['global', 'project'] },
+      { name: '--mode <mode>', help: 'Skill install sync mode (auto, link, copy).', choices: ['auto', 'link', 'copy'] },
+      { name: '--workspace', help: 'Create the gitignored .orizu/ workspace without prompting.' },
+      { name: '--no-workspace', help: 'Skip workspace creation.' },
+      { name: '--no-install', help: 'Skip the agent integration phase.' },
+      { name: '--no-handoff', help: 'Skip printing the coding-agent setup prompt.' },
+      { name: '--launch <agent>', help: 'Launch a detected coding agent with the setup prompt (interactive terminals only).', choices: ['claude', 'codex'] },
+      { name: '--skip-login', help: 'Skip the authentication phase.' },
+      { name: '--yes', help: 'Apply changes without per-step confirmation prompts.' },
+      { name: '--dry-run', help: 'Preview every planned change without writing.' },
+      { name: '--no-input', help: 'Never prompt; behave as in a non-interactive terminal.' },
+      { name: '--json', help: 'Emit the setup summary as JSON.' },
+    ],
+    examples: [
+      'orizu setup',
+      'orizu setup --agent claude --agent codex --yes',
+      'orizu setup --skip-login --no-workspace --dry-run',
+    ],
+  },
+  {
+    path: ['setup', 'prompt'],
+    usage: 'orizu setup prompt',
+    summary: 'Print the coding-agent setup prompt for repo-specific Orizu adoption.',
+    group: 'Agent setup',
+    examples: ['orizu setup prompt', 'claude "$(orizu setup prompt)"'],
+  },
   {
     path: ['install-skill'],
-    usage: 'orizu install-skill [--target <target>]... [--yes] [--dry-run]',
-    summary: 'Install the bundled Orizu CLI skill locally for coding agents.',
+    usage: 'orizu install-skill [--agent <claude|codex>]... [--scope global|project] [--mode auto|link|copy] [--target <target>]... [--yes] [--dry-run]',
+    summary: 'Set up the Orizu skill for your coding agents (Claude Code, Codex/Open Agent Skills, or project instructions).',
     group: 'Agent setup',
     aliases: [['skills', 'install']],
     options: [
+      {
+        name: '--agent <agent>',
+        help: 'Coding agent to set up. Repeat for multiple agents.',
+        repeatable: true,
+        choices: ['claude', 'codex'],
+      },
+      {
+        name: '--scope <scope>',
+        help: 'Where the install lives: global installs for you across all projects (default); project installs into the current repo.',
+        choices: ['global', 'project'],
+      },
+      {
+        name: '--mode <mode>',
+        help: 'How installs stay in sync with the CLI: auto (default) symlinks when the CLI install path is stable and copies otherwise; link forces a symlink; copy forces a full copy with sync metadata. Project-scope installs always copy.',
+        choices: ['auto', 'link', 'copy'],
+      },
       {
         name: '--target <target>',
-        help: 'Install destination. Repeat for multiple targets.',
+        help: 'Advanced: explicit install destination ID. Repeat for multiple targets.',
         repeatable: true,
-        choices: ['agent-user', 'codex-project', 'claude-user', 'claude-project', 'agents-md'],
+        choices: ['agent-user', 'agents-project', 'codex-project', 'claude-user', 'claude-project', 'agents-md'],
       },
       { name: '--yes', help: 'Replace an existing managed skill or AGENTS.md section without prompting.' },
       { name: '--dry-run', help: 'Show planned writes without changing files.' },
     ],
     examples: [
-      'orizu install-skill --target agent-user --yes',
-      'orizu install-skill --target codex-project --target agents-md',
-      'orizu skills install --target claude-user --dry-run',
+      'orizu install-skill --agent claude --agent codex --yes',
+      'orizu install-skill --agent claude --scope project --yes',
+      'orizu install-skill --target agents-md --dry-run',
+    ],
+  },
+  {
+    path: ['skills', 'status'],
+    usage: 'orizu skills status [--json]',
+    summary: 'Report installed Orizu skill targets and whether each is in sync with the CLI.',
+    group: 'Agent setup',
+    options: [
+      { name: '--json', help: 'Emit machine-readable status for every known install target.' },
+    ],
+    examples: ['orizu skills status', 'orizu skills status --json'],
+  },
+  {
+    path: ['skills', 'update'],
+    usage: 'orizu skills update [--dry-run] [--json]',
+    summary: 'Refresh stale copied skill installs and repair broken symlinks.',
+    group: 'Agent setup',
+    options: [
+      { name: '--dry-run', help: 'Show which installs would be refreshed without changing files.' },
+      { name: '--json', help: 'Emit machine-readable update results.' },
+    ],
+    examples: ['orizu skills update', 'orizu skills update --dry-run'],
+  },
+  {
+    path: ['skills', 'path'],
+    usage: 'orizu skills path [--skill-md] [--json]',
+    summary: 'Print where the bundled Orizu skill lives so agents can read it without installing.',
+    group: 'Agent setup',
+    options: [
+      { name: '--skill-md', help: 'Print the full path to SKILL.md instead of the skill root directory.' },
+      { name: '--json', help: 'Emit machine-readable metadata: name, root, skillMd, source, cliVersion, skillHash.' },
+    ],
+    examples: [
+      'orizu skills path',
+      'orizu skills path --skill-md',
+      'orizu skills path --json',
     ],
   },
   {
@@ -158,10 +244,22 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['prompts', 'list'],
-    usage: 'orizu prompts list --project <team/project>',
+    usage: 'orizu prompts list --project <team/project> [--status active|archived|all]',
     summary: 'List prompt artifacts in a project.',
     group: 'Prompts and judges',
   },
+  {
+    path: ['prompts', 'archive'],
+    usage: 'orizu prompts archive <prompt-id-or-name> --project <team/project> [--json]',
+    summary: 'Mark a prompt artifact as archived.',
+    group: 'Prompts and judges',
+  },
+  {
+    path: ['prompts', 'restore'],
+    usage: 'orizu prompts restore <prompt-id-or-name> --project <team/project> [--json]',
+    summary: 'Restore an archived prompt artifact to active status.',
+    group: 'Prompts and judges',
+  },
   {
     path: ['prompts', 'comments'],
     usage: 'orizu prompts comments <prompt-id-or-name> --project <team/project> [--label <label> | --version <id>] [--json]',
@@ -200,7 +298,7 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['judges', 'list'],
-    usage: 'orizu judges list --project <team/project>',
+    usage: 'orizu judges list --project <team/project> [--status active|archived|all]',
     summary: 'List judge prompt artifacts in a project.',
     group: 'Prompts and judges',
   },
@@ -284,7 +382,7 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['optimizations', 'run-gepa'],
-    usage: '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] [--num-threads auto|N] [--log-dir logs]',
+    usage: '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] [--budget auto|light|medium|heavy | --max-metric-calls <n> | --max-full-evals <n> | --max-iterations <n>] [--num-threads auto|N] [--reflection-retry-attempts N] [--reflection-http-timeout-seconds N] [--log-dir logs]',
     summary: 'Run the bundled GEPA-style optimizer locally and stream events.',
     group: 'Optimizations',
   },
@@ -377,20 +475,20 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['tasks', 'create'],
-    usage: 'orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]',
-    summary: 'Create a draft review task by default, or publish immediately with --publish and assignees.',
+    usage: 'orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2> | --assignment-file <path>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]',
+    summary: 'Create a draft review task by default, with auto distribution or an explicit row-assignment JSONL file.',
     group: 'Tasks',
   },
   {
     path: ['tasks', 'publish'],
-    usage: 'orizu tasks publish --task <taskId> --assignees <userId1,userId2> [--json]',
+    usage: 'orizu tasks publish --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--json]',
     summary: 'Publish an approved draft task and assign reviewers.',
     group: 'Tasks',
   },
   {
     path: ['tasks', 'assign'],
-    usage: 'orizu tasks assign --task <taskId> --assignees <userId1,userId2>',
-    summary: 'Assign a task to canonical user IDs.',
+    usage: 'orizu tasks assign --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--replace-existing] [--json]',
+    summary: 'Assign a task with auto distribution or an explicit row-assignment JSONL file.',
     group: 'Tasks',
   },
   {
@@ -658,6 +756,7 @@ export function getCapabilities(version: string) {
   return {
     name: 'orizu',
     version,
+    globalOptions: GLOBAL_OPTIONS.map(([name, help]) => ({ name, help })),
     commands: COMMAND_DOCS.map(doc => ({
       name: commandKey(doc.path),
       usage: doc.usage,