orizu 0.3.7 → 0.4.0

package/README.md

@@ -35,15 +35,56 @@ Install the CLI globally with your package manager:
 | pnpm | `pnpm add -g orizu` |
 | Bun | `bun add -g orizu` |
 
-Install the companion coding-agent skill from the CLI package:
+Then run the guided setup — it signs you in, sets up your coding agents,
+optionally creates a gitignored `.orizu/` workspace, and hands your agent a
+prompt to plan repo-specific Orizu adoption:
 
 ```bash
-orizu install-skill --target agent-user --yes
+orizu setup
 ```
 
-The npm package ships the skill alongside the CLI. Use `orizu install-skill --help`
-to see all supported targets, including Codex project, Claude user/project, and
-`AGENTS.md` installs.
+Or install just the companion coding-agent skill:
+
+```bash
+orizu install-skill --agent claude --agent codex --yes
+```
+
+First-class plugin packages for Codex and Claude Code live under `plugins/`
+in this repository. Plugins bundle the same skill; the CLI remains the runtime
+either way.
+
+```bash
+# Codex
+codex plugin marketplace add <owner>/<this-repo>
+codex plugin add orizu@orizu-plugins
+
+# Claude Code (inside a session)
+/plugin marketplace add <owner>/<this-repo>
+/plugin install orizu@orizu
+```
+
+The npm package ships the skill alongside the CLI. Run `orizu install-skill` in
+a terminal for an interactive chooser (Claude Code and Codex preselected,
+user-level installs by default), or use `orizu install-skill --help` for
+project-scope installs, sync modes, and advanced targets including the managed
+`AGENTS.md` section. Keep installs in sync after CLI upgrades with
+`orizu skills status` and `orizu skills update`.
+
+Coding agents can also read the bundled skill directly without installing it:
+
+```bash
+orizu skills path --json
+```
+
+This prints the skill location plus source metadata (`name`, `root`, `skillMd`,
+`source`, `cliVersion`, `skillHash`), so an agent can go from `npx orizu --help`
+to reading `SKILL.md` in two commands and verify the guidance matches the CLI
+that supplied it.
+
+Agents are first-class users of this CLI: **every command supports `--json`**
+(as a prefix, `orizu --json teams list`, or a trailing flag) and emits a single
+machine-readable JSON document instead of formatted text. Discover the full
+command surface, including global options, with `orizu capabilities --json`.
 
 ## Authentication
 
@@ -82,6 +123,10 @@ orizu logout
     <td>Install the bundled agent skill</td>
     <td><code>orizu install-skill --target agent-user --yes</code></td>
   </tr>
+  <tr>
+    <td>Locate the bundled skill (read-only)</td>
+    <td><code>orizu skills path --json</code></td>
+  </tr>
   <tr>
     <td>Inspect CLI capabilities as JSON</td>
     <td><code>orizu capabilities --json</code></td>
@@ -121,7 +166,11 @@ orizu logout
   </tr>
   <tr>
     <td>List prompts</td>
-    <td><code>orizu prompts list --project ops-eval/support-qa</code></td>
+    <td><code>orizu prompts list --project ops-eval/support-qa [--status active|archived|all]</code></td>
+  </tr>
+  <tr>
+    <td>Archive or restore a prompt</td>
+    <td><code>orizu prompts archive &lt;promptIdOrName&gt; --project ops-eval/support-qa</code><br><code>orizu prompts restore &lt;promptIdOrName&gt; --project ops-eval/support-qa</code></td>
   </tr>
   <tr>
     <td>Show prompt comments</td>

package/dist/banner.js

@@ -0,0 +1,20 @@
+// Faceted rendering of the Orizu origami swan (public/orizu-swan.svg):
+// each polygon is filled with block/triangle glyphs and shrunk slightly so
+// the seams between origami facets stay visible, matching the brand mark.
+// Printed uncolored so it renders in the terminal's default foreground.
+export const ORIZU_BANNER = `     ▄▄
+   ▄▜▛ ██▙
+  ▟▀   ◥██▛
+        ▀▜▄
+       ▄▟█
+     ▄███
+   ▄████◤        ▄▄▄█▛
+ ▟█████◤     ▄▄█████▛
+ ▄▀███◤  ▄█████████▛
+ ◥█▄▀▛▐█▄◥▜███████▛ ███▀
+  ▜██ ████▄◥▜████▛ ██▀
+   █ ███████▄ ▜█▛ █▀
+    ▐█████████◣  ▀`;
+export function renderBanner() {
+    return ORIZU_BANNER;
+}

package/dist/csv.js

@@ -1,4 +1,105 @@
-export function parseCSV(csvText) {
+/**
+ * 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) {
+        super(message);
+        this.name = 'CSVResourceLimitError';
+    }
+}
+// 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) {
+    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, options) {
+    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, options) {
+    const maxRows = options.maxRows ?? DEFAULT_CSV_MAX_ROWS;
+    if (rowCount > maxRows) {
+        throw new CSVResourceLimitError(`CSV has too many rows (max ${maxRows})`);
+    }
+}
+function enforceFieldLimits(row, options) {
+    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, row, options) {
+    // 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, options = {}) {
+    enforceCsvTextLimit(csvText, options);
     const result = [];
     let currentRow = [];
     let currentField = '';
@@ -9,6 +110,7 @@ export function parseCSV(csvText) {
         const nextChar = csvText[i + 1];
         if (char === '"') {
             if (inQuotes && nextChar === '"') {
+                // Escaped quote - convert "" to "
                 currentField += '"';
                 i += 2;
                 continue;
@@ -27,9 +129,7 @@ export function parseCSV(csvText) {
             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 = '';
                 }
@@ -45,16 +145,24 @@ export function parseCSV(csvText) {
         currentField += char;
         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) {
-    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, options = {}) {
+    const rows = parseCSV(csvText, options);
     if (rows.length < 2) {
         return [];
     }

package/dist/help.js

@@ -1,4 +1,5 @@
 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.'],
@@ -51,26 +52,111 @@ export const COMMAND_DOCS = [
         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',
         ],
     },
     {
@@ -133,10 +219,22 @@ export const COMMAND_DOCS = [
     },
     {
         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]',
@@ -175,7 +273,7 @@ export const COMMAND_DOCS = [
     },
     {
         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',
     },
@@ -259,7 +357,7 @@ export const COMMAND_DOCS = [
     },
     {
         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',
     },
@@ -593,6 +691,7 @@ export function getCapabilities(version) {
     return {
         name: 'orizu',
         version,
+        globalOptions: GLOBAL_OPTIONS.map(([name, help]) => ({ name, help })),
         commands: COMMAND_DOCS.map(doc => ({
             name: commandKey(doc.path),
             usage: doc.usage,