@eve-horizon/cli 0.0.1

package/README.md

@@ -0,0 +1,275 @@
+# Eve Horizon CLI
+
+Published CLI (npx) for interacting with the Eve Horizon API. Dev/ops tooling lives in `./bin/eh`.
+
+```bash
+npx @eve/cli --help
+```
+
+## Philosophy
+
+The CLI is the **primary interface** for Eve Horizon, designed for humans and AI agents. The REST API is the substrate: every operation is exposed via HTTP, and the CLI is a thin wrapper that handles argument parsing and output formatting. It does not bypass the API or contain business logic.
+
+See [API Philosophy](../../docs/system/api-philosophy.md) and [OpenAPI](../../docs/system/openapi.md).
+
+## Profiles (defaults + credentials)
+
+Profiles store API URL, default org/project IDs, default harness, and Supabase auth config.
+
+```bash
+# Create or update a profile
+eve profile set local \
+  --api-url http://localhost:4701 \
+  --org org_defaulttestorg \
+  --project proj_xxx
+
+# Set default harness (with optional variant)
+eve profile set --harness mclaude
+eve profile set --harness mclaude:fast   # harness with variant
+
+# Set active profile
+eve profile use local
+
+# Show active profile
+eve profile show
+```
+
+Profile harness defaults are used when scheduling jobs.
+The `--harness` flag accepts `harness` or `harness:variant` format everywhere.
+Priority: `--harness` flag > job hints > profile default > system default.
+
+### Supabase config (cloud auth)
+
+Store Supabase settings in a profile (recommended for cloud stacks):
+
+```bash
+eve profile set prod \
+  --api-url https://api.eve-horizon.example.com \
+  --supabase-url https://your-project.supabase.co \
+  --supabase-anon-key <anon-key>
+```
+
+## Auth
+
+Auth is **optional** per stack. When the server has `EVE_AUTH_ENABLED=false`, login is not required.
+Supabase settings can be stored in a profile or provided via `EVE_SUPABASE_URL` and
+`EVE_SUPABASE_ANON_KEY`.
+
+The CLI will refresh access tokens automatically if a refresh token is available.
+
+```bash
+# Login (cloud)
+eve auth login --email you@example.com --password '...' \
+  --profile prod
+
+# Status / whoami
+eve auth status
+eve auth whoami
+
+# Logout
+eve auth logout
+```
+
+## Commands
+
+### Organizations
+
+```bash
+eve org ensure "My Org"
+eve org list
+eve org get org_xxx
+eve org update org_xxx --name "New Name"
+```
+
+### Projects
+
+```bash
+eve project ensure --name my-project --slug MyProj --repo-url https://github.com/org/repo
+eve project list
+eve project get proj_xxx
+```
+
+### Jobs
+
+Jobs follow a phase-based lifecycle: `idea` → `backlog` → `ready` → `active` → `review` → `done`
+
+Jobs created without a `--phase` flag default to `ready`, making them immediately schedulable.
+
+```bash
+# Create a job (defaults to ready phase)
+eve job create --description "Fix the login bug in auth.ts"
+eve job create --description "Add dark mode" --priority 1 --harness mclaude
+
+# List and filter jobs
+eve job list --phase ready
+eve job ready                    # Schedulable jobs (ready, not blocked)
+eve job blocked                  # Jobs waiting on dependencies
+
+# View job details
+eve job show MyProj-abc123
+eve job tree MyProj-abc123       # Hierarchical view
+
+# Update jobs
+eve job update MyProj-abc123 --phase active --assignee agent-1
+eve job close MyProj-abc123 --reason "Work completed"
+eve job cancel MyProj-abc123 --reason "No longer needed"
+
+# Dependencies
+eve job dep add MyProj-abc123 MyProj-def456   # abc123 depends on def456
+eve job dep list MyProj-abc123
+
+# Claim/release workflow (typically used by scheduler/agents)
+eve job claim MyProj-abc123 --harness mclaude
+eve job release MyProj-abc123 --reason "Need more info"
+eve job attempts MyProj-abc123
+
+# Job execution and monitoring
+eve job logs MyProj-abc123
+eve job result MyProj-abc123 --format full    # Get job results (text|json|full)
+eve job result MyProj-abc123 --attempt 2      # Get results from specific attempt
+eve job wait MyProj-abc123 --timeout 300      # Wait for job completion
+eve job wait MyProj-abc123 --quiet --json     # Wait quietly, JSON output
+eve job follow MyProj-abc123                  # Stream logs in real-time via SSE
+eve job follow MyProj-abc123 --raw            # Stream raw JSON lines
+eve job follow MyProj-abc123 --no-result      # Stream logs without final result
+
+# Review workflow
+eve job submit MyProj-abc123 --summary "Implemented fix"
+eve job approve MyProj-abc123 --comment "LGTM"
+eve job reject MyProj-abc123 --reason "Missing tests"
+```
+
+#### Job Results
+
+Fetch and display completed job results:
+
+```bash
+# Show full job result (default format)
+eve job result MyProj-abc123
+
+# Get results in different formats
+eve job result MyProj-abc123 --format text    # Plain text output only
+eve job result MyProj-abc123 --format json    # Full JSON structure
+eve job result MyProj-abc123 --format full    # Formatted with metadata (default)
+
+# Get results from a specific attempt
+eve job result MyProj-abc123 --attempt 2
+```
+
+#### Waiting for Job Completion
+
+Block until a job completes, with optional timeout:
+
+```bash
+# Wait for job to complete (default timeout: 300s)
+eve job wait MyProj-abc123
+
+# Custom timeout (max 300s enforced by API)
+eve job wait MyProj-abc123 --timeout 120
+
+# Quiet mode (no progress output)
+eve job wait MyProj-abc123 --quiet
+
+# JSON output format
+eve job wait MyProj-abc123 --json
+```
+
+Exit codes:
+- `0`: Job completed successfully
+- `1`: Job failed
+- `124`: Timeout reached
+- `125`: Job was cancelled
+
+#### Real-time Log Streaming
+
+Stream job logs in real-time using Server-Sent Events (SSE):
+
+```bash
+# Stream logs with timestamps and formatted output
+eve job follow MyProj-abc123
+
+# Stream raw JSON lines (for parsing/filtering)
+eve job follow MyProj-abc123 --raw
+
+# Stream logs without printing final result
+eve job follow MyProj-abc123 --no-result
+```
+
+The `follow` command connects to the job's SSE endpoint and displays logs as they are generated. It shows:
+- Timestamps for each log entry
+- Tool names and actions
+
+### Secrets
+
+Secrets can be stored at user/org/project scope. Values are never returned in plaintext; `show` returns a masked value.
+
+```bash
+# Project secret
+eve secrets set GITHUB_TOKEN ghp_xxx --project proj_xxx --type github_token
+eve secrets list --project proj_xxx
+eve secrets show GITHUB_TOKEN --project proj_xxx
+eve secrets delete GITHUB_TOKEN --project proj_xxx
+
+# Import host secrets from .env
+eve secrets import --project proj_xxx --file .env
+```
+- Formatted, human-readable output
+
+Use `--raw` for programmatic consumption or when piping to other tools.
+
+#### Scheduling Hints
+
+Jobs can include hints for the scheduler:
+
+```bash
+eve job create --description "Heavy computation" \
+  --harness mclaude:fast \
+  --worker-type gpu \
+  --permission auto_edit \
+  --timeout 7200
+```
+
+#### Creating Sub-Jobs (for agents)
+
+Agents can create and optionally claim sub-jobs inline:
+
+```bash
+# Create sub-job under parent
+eve job create --parent MyProj-abc123 --description "Implement feature X"
+
+# Create and immediately claim (for inline execution)
+eve job create --parent $EVE_JOB_ID --description "Sub-task" --claim
+```
+
+Environment variables for agent context:
+- `EVE_PROJECT_ID` - Current project
+- `EVE_JOB_ID` - Current job being executed
+- `EVE_ATTEMPT_ID` - Current attempt UUID
+- `EVE_AGENT_ID` - Agent identifier
+
+### Harnesses
+
+```bash
+eve harness list              # List available harnesses
+eve harness get mclaude       # Show harness details and auth status
+```
+
+## Pagination
+
+List endpoints accept `--limit` and `--offset`. Default limit is **10**, newest first.
+
+```bash
+eve job list --limit 10 --offset 20
+```
+
+## Dev CLI
+
+Local dev/ops tooling:
+
+```bash
+./bin/eh --help
+./bin/eh dev start
+./bin/eh k8s start     # Default runtime
+./bin/eh docker start  # Quick dev loop
+./bin/eh db migrate
+```

package/bin/eve.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js');

package/dist/commands/api.js

@@ -0,0 +1,350 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleApi = handleApi;
+exports.handleSpec = handleSpec;
+exports.fetchApiSpec = fetchApiSpec;
+const args_1 = require("../lib/args");
+const client_1 = require("../lib/client");
+const output_1 = require("../lib/output");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+async function handleApi(subcommand, positionals, flags, context) {
+    const jsonOutput = Boolean(flags.json);
+    switch (subcommand) {
+        case 'list':
+            return handleList(positionals, flags, context, jsonOutput);
+        case 'show':
+            return handleShow(positionals, flags, context, jsonOutput);
+        case 'spec':
+            return handleSpec(positionals, flags, context, jsonOutput);
+        case 'refresh':
+            return handleRefresh(positionals, flags, context, jsonOutput);
+        case 'examples':
+            return handleExamples(positionals, flags, context, jsonOutput);
+        case 'call':
+            return handleCall(positionals, flags, context);
+        default:
+            throw new Error('Usage: eve api <list|show|spec|refresh|examples|call>\n' +
+                '  list [project]                          - list API sources\n' +
+                '  show <name> [project]                   - show a single API source\n' +
+                '  spec <name> [project]                   - show cached API spec\n' +
+                '  refresh <name> [project]                - refresh cached API spec\n' +
+                '  examples <name> [project]               - print curl examples from spec\n' +
+                '  call <name> <method> <path> [options]   - call an API with Eve auth');
+    }
+}
+async function handleList(positionals, flags, context, jsonOutput) {
+    const projectId = positionals[0] ?? (0, args_1.getStringFlag)(flags, ['project']) ?? context.projectId;
+    if (!projectId) {
+        throw new Error('Usage: eve api list [project] [--project=<id>] [--env=<name>]');
+    }
+    const query = buildQuery({
+        env: (0, args_1.getStringFlag)(flags, ['env']),
+    });
+    const response = await (0, client_1.requestJson)(context, `/projects/${projectId}/apis${query}`);
+    if (jsonOutput) {
+        (0, output_1.outputJson)(response, jsonOutput);
+        return;
+    }
+    if (!response.data || response.data.length === 0) {
+        console.log('No API sources found.');
+        return;
+    }
+    formatApiSourcesTable(response.data);
+}
+async function handleShow(positionals, flags, context, jsonOutput) {
+    const name = positionals[0] ?? (0, args_1.getStringFlag)(flags, ['name']);
+    const projectId = positionals[1] ?? (0, args_1.getStringFlag)(flags, ['project']) ?? context.projectId;
+    const env = (0, args_1.getStringFlag)(flags, ['env']);
+    if (!name || !projectId) {
+        throw new Error('Usage: eve api show <name> [project] [--project=<id>] [--env=<name>]');
+    }
+    const query = buildQuery({ env });
+    const response = await (0, client_1.requestJson)(context, `/projects/${projectId}/apis/${name}${query}`);
+    (0, output_1.outputJson)(response, jsonOutput);
+}
+async function handleSpec(positionals, flags, context, jsonOutput) {
+    const name = positionals[0] ?? (0, args_1.getStringFlag)(flags, ['name']);
+    const projectId = positionals[1] ?? (0, args_1.getStringFlag)(flags, ['project']) ?? context.projectId;
+    const env = (0, args_1.getStringFlag)(flags, ['env']);
+    if (!name || !projectId) {
+        throw new Error('Usage: eve api spec <name> [project] [--project=<id>] [--env=<name>]');
+    }
+    const spec = await fetchApiSpec(context, projectId, name, env);
+    if (typeof spec.data === 'string') {
+        (0, output_1.outputJson)(spec.data, jsonOutput, spec.raw);
+        return;
+    }
+    (0, output_1.outputJson)(spec.data, jsonOutput);
+}
+async function handleRefresh(positionals, flags, context, jsonOutput) {
+    const name = positionals[0] ?? (0, args_1.getStringFlag)(flags, ['name']);
+    const projectId = positionals[1] ?? (0, args_1.getStringFlag)(flags, ['project']) ?? context.projectId;
+    const env = (0, args_1.getStringFlag)(flags, ['env']);
+    if (!name || !projectId) {
+        throw new Error('Usage: eve api refresh <name> [project] [--project=<id>] [--env=<name>]');
+    }
+    const query = buildQuery({ env });
+    const response = await (0, client_1.requestJson)(context, `/projects/${projectId}/apis/${name}/refresh${query}`, {
+        method: 'POST',
+    });
+    (0, output_1.outputJson)(response, jsonOutput);
+}
+async function handleExamples(positionals, flags, context, jsonOutput) {
+    const name = positionals[0] ?? (0, args_1.getStringFlag)(flags, ['name']);
+    const projectId = positionals[1] ?? (0, args_1.getStringFlag)(flags, ['project']) ?? context.projectId;
+    const env = (0, args_1.getStringFlag)(flags, ['env']);
+    if (!name || !projectId) {
+        throw new Error('Usage: eve api examples <name> [project] [--project=<id>] [--env=<name>]');
+    }
+    const query = buildQuery({ env });
+    const api = await (0, client_1.requestJson)(context, `/projects/${projectId}/apis/${name}${query}`);
+    const spec = await fetchApiSpec(context, projectId, name, env);
+    if (jsonOutput) {
+        (0, output_1.outputJson)({ api, spec: spec.data }, jsonOutput);
+        return;
+    }
+    if (!spec.data || typeof spec.data !== 'object') {
+        throw new Error('API spec is not JSON; examples require a JSON OpenAPI spec.');
+    }
+    const examples = buildCurlExamples(api, spec.data);
+    if (examples.length === 0) {
+        console.log('No endpoints found in spec.');
+        return;
+    }
+    console.log(`API examples for ${api.name} (${api.type})`);
+    console.log('');
+    examples.forEach((example) => {
+        console.log(example);
+    });
+}
+async function handleCall(positionals, flags, context) {
+    const name = positionals[0];
+    const methodInput = positionals[1];
+    const pathInput = positionals[2];
+    if (!name || !methodInput || !pathInput) {
+        throw new Error('Usage: eve api call <name> <method> <path> [--json <payload>] [--jq <expr>]');
+    }
+    const projectId = (0, args_1.getStringFlag)(flags, ['project']) ?? context.projectId;
+    const env = (0, args_1.getStringFlag)(flags, ['env']);
+    if (!projectId) {
+        throw new Error('Missing project id. Provide --project or set a profile default.');
+    }
+    const query = buildQuery({ env });
+    const api = await (0, client_1.requestJson)(context, `/projects/${projectId}/apis/${name}${query}`);
+    const jqExpr = (0, args_1.getStringFlag)(flags, ['jq']);
+    const printCurl = Boolean(flags['print-curl']);
+    const jsonPayloadFlag = flags.json;
+    if (jsonPayloadFlag === true) {
+        throw new Error('Usage: --json <payload|@file>');
+    }
+    const graphqlFlag = flags.graphql;
+    const graphqlQuery = graphqlFlag === true ? undefined : (0, args_1.getStringFlag)(flags, ['graphql']);
+    if (graphqlFlag === true && !graphqlQuery) {
+        throw new Error('Usage: --graphql <query|@file>');
+    }
+    if (graphqlQuery && jsonPayloadFlag) {
+        throw new Error('Use --variables for GraphQL variables; --json is for JSON bodies.');
+    }
+    const variablesFlag = (0, args_1.getStringFlag)(flags, ['variables']);
+    const variables = variablesFlag ? resolveJsonInput(variablesFlag) : undefined;
+    const jsonBody = typeof jsonPayloadFlag === 'string' ? resolveJsonInput(jsonPayloadFlag) : undefined;
+    const graphqlBody = graphqlQuery
+        ? {
+            query: resolveTextInput(graphqlQuery),
+            ...(variables ? { variables } : {}),
+        }
+        : undefined;
+    const body = graphqlBody ?? jsonBody;
+    const method = methodInput.toUpperCase();
+    const path = resolveApiPath(api.base_url, pathInput);
+    const tokenOverride = (0, args_1.getStringFlag)(flags, ['token']);
+    const authToken = tokenOverride ?? process.env.EVE_JOB_TOKEN ?? context.token;
+    if (printCurl) {
+        const curl = buildCurlCommand({
+            method,
+            url: path,
+            authToken,
+            jsonBody: body,
+            authHint: tokenOverride ? 'override' : (process.env.EVE_JOB_TOKEN ? 'job' : 'user'),
+        });
+        console.log(curl);
+        return;
+    }
+    const response = await fetch(path, {
+        method,
+        headers: buildApiHeaders(authToken, body),
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${text}`);
+    }
+    const { data, jsonText } = parseResponse(text);
+    if (jqExpr) {
+        if (!jsonText) {
+            throw new Error('Cannot apply --jq to a non-JSON response.');
+        }
+        const output = runJq(jqExpr, jsonText);
+        process.stdout.write(output);
+        return;
+    }
+    if (data !== undefined) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    process.stdout.write(text);
+}
+function buildQuery(params) {
+    const query = Object.entries(params)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join('&');
+    return query ? `?${query}` : '';
+}
+function formatApiSourcesTable(apis) {
+    const nameWidth = Math.max(4, ...apis.map((api) => api.name.length));
+    const typeWidth = Math.max(4, ...apis.map((api) => api.type.length));
+    console.log(`${'NAME'.padEnd(nameWidth)}  ${'TYPE'.padEnd(typeWidth)}  BASE URL`);
+    console.log(`${'-'.repeat(nameWidth)}  ${'-'.repeat(typeWidth)}  --------`);
+    apis.forEach((api) => {
+        console.log(`${api.name.padEnd(nameWidth)}  ${api.type.padEnd(typeWidth)}  ${api.base_url}`);
+    });
+}
+async function fetchApiSpec(context, projectId, name, env) {
+    const query = buildQuery({ env });
+    const response = await (0, client_1.requestJson)(context, `/projects/${projectId}/apis/${name}/spec${query}`);
+    if (response && typeof response === 'object' && 'schema' in response) {
+        const schema = response.schema;
+        if (typeof schema === 'string') {
+            return { data: schema.trim(), raw: schema };
+        }
+        return { data: schema, raw: JSON.stringify(schema) };
+    }
+    if (typeof response === 'string') {
+        return { data: response.trim(), raw: response };
+    }
+    return { data: response, raw: JSON.stringify(response) };
+}
+function buildCurlExamples(api, spec) {
+    const paths = spec.paths ?? {};
+    const examples = [];
+    Object.entries(paths).forEach(([path, methods]) => {
+        Object.entries(methods).forEach(([method, operation]) => {
+            const lower = method.toLowerCase();
+            if (!['get', 'post', 'put', 'patch', 'delete'].includes(lower)) {
+                return;
+            }
+            const requestBody = operation.requestBody?.content?.['application/json'];
+            const examplePayload = extractExamplePayload(requestBody);
+            const needsBody = ['post', 'put', 'patch'].includes(lower);
+            const curl = buildCurlCommand({
+                method: lower.toUpperCase(),
+                url: resolveApiPath(api.base_url, path),
+                authToken: api.auth_mode === 'eve' ? '$EVE_JOB_TOKEN' : undefined,
+                jsonBody: needsBody ? (examplePayload ?? {}) : undefined,
+                authHint: 'job',
+            });
+            const summary = operation.summary ?? operation.description;
+            if (summary) {
+                examples.push(`# ${summary}`);
+            }
+            examples.push(curl);
+            examples.push('');
+        });
+    });
+    return examples;
+}
+function extractExamplePayload(requestBody) {
+    if (!requestBody)
+        return undefined;
+    if (requestBody.example !== undefined)
+        return requestBody.example;
+    const examples = requestBody.examples ? Object.values(requestBody.examples) : [];
+    if (examples.length === 0)
+        return undefined;
+    return examples[0]?.value;
+}
+function resolveApiPath(baseUrl, path) {
+    if (path.startsWith('http://') || path.startsWith('https://')) {
+        return path;
+    }
+    if (!baseUrl) {
+        return path;
+    }
+    const trimmedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    const trimmedPath = path.startsWith('/') ? path : `/${path}`;
+    return `${trimmedBase}${trimmedPath}`;
+}
+function buildApiHeaders(authToken, body) {
+    const headers = {};
+    if (authToken) {
+        headers.Authorization = `Bearer ${authToken}`;
+    }
+    if (body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+    }
+    return headers;
+}
+function resolveJsonInput(value) {
+    const text = resolveTextInput(value);
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON payload: ${error.message}`);
+    }
+}
+function resolveTextInput(value) {
+    if (value.startsWith('@')) {
+        const filePath = (0, node_path_1.resolve)(value.slice(1));
+        return (0, node_fs_1.readFileSync)(filePath, 'utf-8');
+    }
+    if (value.trim().startsWith('{') || value.trim().startsWith('[')) {
+        return value;
+    }
+    if ((0, node_fs_1.existsSync)(value)) {
+        return (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(value), 'utf-8');
+    }
+    return value;
+}
+function parseResponse(text) {
+    if (!text)
+        return { data: undefined, jsonText: undefined };
+    try {
+        const data = JSON.parse(text);
+        return { data, jsonText: JSON.stringify(data) };
+    }
+    catch {
+        return { data: undefined, jsonText: undefined };
+    }
+}
+function runJq(expression, jsonText) {
+    const result = (0, node_child_process_1.spawnSync)('jq', [expression], {
+        input: jsonText,
+        encoding: 'utf-8',
+    });
+    if (result.error) {
+        if (result.error.code === 'ENOENT') {
+            throw new Error('jq is not installed. Install jq to use --jq output filtering.');
+        }
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        throw new Error(result.stderr || 'jq failed to process the response.');
+    }
+    return result.stdout ?? '';
+}
+function buildCurlCommand(options) {
+    const parts = ['curl', '-sS', '-X', options.method, `'${options.url}'`];
+    if (options.authToken) {
+        const tokenValue = options.authHint === 'job' ? '$EVE_JOB_TOKEN' : options.authToken;
+        parts.push(`-H 'Authorization: Bearer ${tokenValue}'`);
+    }
+    if (options.jsonBody !== undefined) {
+        parts.push("-H 'Content-Type: application/json'");
+        parts.push(`-d '${JSON.stringify(options.jsonBody)}'`);
+    }
+    return parts.join(' ');
+}