rubrkit 0.1.0

package/src/config.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { usageError } from './errors.js';
+
+export const DEFAULT_API_URL = 'https://rubrkit.com/api/v1';
+
+const CONFIG_FIELDS = new Set([
+    'apiUrl',
+    'destination',
+    'agent',
+    'artifactBundle',
+    'artifact',
+    'rubric',
+    'format',
+    'output',
+    'failUnder',
+    'failOn',
+    'all',
+    'yes',
+    'dryRun',
+    'force',
+    'prune',
+    'updateOnly',
+    'ci',
+    'local',
+    'remote',
+    'noAi',
+    'watch',
+    'changed',
+]);
+
+/**
+ * @param {{
+ *   parsed: ReturnType<import('./args.js').parseArgs>,
+ *   env?: Record<string, string | undefined>,
+ *   cwd?: string,
+ *   fsImpl?: Pick<typeof fs, 'readFile' | 'stat'>,
+ * }} params
+ */
+export async function resolveConfig({ parsed, env = process.env, cwd = process.cwd(), fsImpl = fs }) {
+    const config = await loadConfig({ configPath: stringOption(parsed.options.config), cwd, fsImpl });
+    const options = parsed.options;
+
+    return {
+        command: parsed.command,
+        selector: parsed.selector,
+        apiKey: stringOption(options['api-key']) ?? env.RUBRKIT_API_KEY ?? null,
+        apiUrl: normalizeApiUrl(stringOption(options['api-url']) ?? env.RUBRKIT_API_URL ?? stringOption(config.apiUrl) ?? DEFAULT_API_URL),
+        destination: stringOption(options.destination) ?? stringOption(config.destination) ?? cwd,
+        agent: stringOption(options.agent) ?? stringOption(config.agent) ?? 'auto',
+        artifactBundle: stringOption(options['artifact-bundle']) ?? stringOption(config.artifactBundle) ?? null,
+        artifact: stringOption(options.artifact) ?? stringOption(config.artifact) ?? null,
+        rubric: stringOption(options.rubric) ?? stringOption(config.rubric) ?? null,
+        format: stringOption(options.format) ?? stringOption(config.format) ?? 'text',
+        output: stringOption(options.output) ?? stringOption(config.output) ?? null,
+        failUnder: numberOption(options['fail-under']) ?? numberOption(config.failUnder),
+        failOn: stringOption(options['fail-on']) ?? stringOption(config.failOn) ?? null,
+        all: booleanOption(options.all) || booleanOption(config.all),
+        yes: booleanOption(options.yes) || booleanOption(config.yes),
+        dryRun: booleanOption(options['dry-run']) || booleanOption(config.dryRun),
+        force: booleanOption(options.force) || booleanOption(config.force),
+        prune: booleanOption(options.prune) || booleanOption(config.prune),
+        updateOnly: booleanOption(options['update-only']) || booleanOption(config.updateOnly),
+        ci: booleanOption(options.ci) || booleanOption(config.ci),
+        local: booleanOption(options.local) || booleanOption(config.local),
+        remote: booleanOption(options.remote) || booleanOption(config.remote),
+        noAi: booleanOption(options['no-ai']) || booleanOption(config.noAi),
+        watch: booleanOption(options.watch) || booleanOption(config.watch),
+        changed: booleanOption(options.changed) || booleanOption(config.changed),
+        configPath: stringOption(options.config) ?? null,
+    };
+}
+
+/**
+ * @param {{ configPath?: string | null, cwd: string, fsImpl: Pick<typeof fs, 'readFile' | 'stat'> }} params
+ */
+async function loadConfig({ configPath, cwd, fsImpl }) {
+    const candidate = configPath ? path.resolve(cwd, configPath) : path.join(cwd, '.rubrkit', 'config.json');
+
+    try {
+        if (!configPath) {
+            await fsImpl.stat(candidate);
+        }
+    } catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return {};
+        }
+
+        throw error;
+    }
+
+    let parsed;
+
+    try {
+        parsed = JSON.parse(await fsImpl.readFile(candidate, 'utf8'));
+    } catch (error) {
+        throw usageError(`Could not read Rubrkit config at ${candidate}: ${error instanceof Error ? error.message : 'invalid JSON'}`);
+    }
+
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw usageError('Rubrkit config must be a JSON object.');
+    }
+
+    if ('apiKey' in parsed || 'api-key' in parsed || 'RUBRKIT_API_KEY' in parsed) {
+        throw usageError('Do not store API keys in Rubrkit config files. Use RUBRKIT_API_KEY or --api-key instead.');
+    }
+
+    for (const field of Object.keys(parsed)) {
+        if (!CONFIG_FIELDS.has(field)) {
+            throw usageError(`Unknown Rubrkit config field "${field}".`);
+        }
+    }
+
+    return parsed;
+}
+
+/**
+ * @param {unknown} value
+ */
+function stringOption(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+/**
+ * @param {unknown} value
+ */
+function booleanOption(value) {
+    return value === true;
+}
+
+/**
+ * @param {unknown} value
+ */
+function numberOption(value) {
+    if (value === undefined || value === null || value === false) {
+        return null;
+    }
+
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * @param {string} value
+ */
+export function normalizeApiUrl(value) {
+    let parsed;
+
+    try {
+        parsed = new URL(value);
+    } catch {
+        throw usageError(`Invalid Rubrkit API URL "${value}".`);
+    }
+
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+        throw usageError('Rubrkit API URL must use http or https.');
+    }
+
+    if (parsed.pathname === '/' || parsed.pathname === '') {
+        parsed.pathname = '/api/v1';
+    }
+
+    parsed.pathname = parsed.pathname.replace(/\/+$/, '');
+    parsed.search = '';
+    parsed.hash = '';
+
+    return parsed.toString().replace(/\/$/, '');
+}

package/src/errors.js

@@ -0,0 +1,55 @@
+export class RubrkitCliError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, exitCode?: number, details?: unknown }} [options]
+     */
+    constructor(message, { code = 'rubrkit_cli_error', exitCode = 1, details = undefined } = {}) {
+        super(message);
+        this.name = 'RubrkitCliError';
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+
+export const EXIT_CODES = {
+    checksFailed: 1,
+    usage: 2,
+    auth: 3,
+    blocked: 4,
+    network: 5,
+};
+
+/**
+ * @param {string} message
+ */
+export function usageError(message) {
+    return new RubrkitCliError(message, { code: 'invalid_cli_usage', exitCode: EXIT_CODES.usage });
+}
+
+/**
+ * @param {string} message
+ */
+export function authError(message) {
+    return new RubrkitCliError(message, { code: 'missing_api_key', exitCode: EXIT_CODES.auth });
+}
+
+/**
+ * @param {string | null | undefined} code
+ * @param {number} [status]
+ */
+export function exitCodeForApiFailure(code, status = 0) {
+    if (status === 401 || status === 403) {
+        return EXIT_CODES.auth;
+    }
+
+    if (['credit_limit_exceeded', 'usage_limit_exceeded', 'ai_circuit_breaker_open'].includes(String(code))) {
+        return EXIT_CODES.blocked;
+    }
+
+    if (status >= 500 || status === 429 || status === 0) {
+        return EXIT_CODES.network;
+    }
+
+    return EXIT_CODES.checksFailed;
+}

package/src/formats.js

@@ -0,0 +1,222 @@
+// @ts-check
+
+import fs from 'node:fs/promises';
+
+/**
+ * @param {{ payload: Record<string, any>, format?: string, output?: string | null, stdout: NodeJS.WritableStream, fsImpl?: typeof fs }} params
+ */
+export async function writeFormattedResult({ payload, format = 'text', output = null, stdout, fsImpl = fs }) {
+    const rendered = renderResult(payload, format);
+
+    if (output) {
+        await fsImpl.writeFile(output, rendered, 'utf8');
+        if (format !== 'json') {
+            stdout.write(`Wrote Rubrkit ${format} report to ${output}\n`);
+        }
+        return;
+    }
+
+    stdout.write(rendered);
+    if (!rendered.endsWith('\n')) {
+        stdout.write('\n');
+    }
+}
+
+/**
+ * @param {Record<string, any>} payload
+ * @param {string} format
+ */
+export function renderResult(payload, format = 'text') {
+    if (format === 'json') {
+        return `${JSON.stringify(payload, null, 2)}\n`;
+    }
+
+    if (format === 'junit') {
+        return renderJUnit(payload);
+    }
+
+    return renderText(payload);
+}
+
+/**
+ * @param {Record<string, any>} payload
+ */
+function renderText(payload) {
+    if (payload.mode === 'remote-dry-run') {
+        return [
+            `Rubrkit ${payload.command} remote dry run`,
+            `Target: ${payload.target ?? '(none)'}`,
+            `Endpoint: ${payload.endpoint}`,
+            `Method: ${payload.method}`,
+            `Polls job: ${payload.pollsJob ? 'yes' : 'no'}`,
+            payload.requiresApiKey ? 'Requires API key: yes' : 'Requires API key: no',
+        ].join('\n') + '\n';
+    }
+
+    if (payload.mode === 'remote') {
+        const job = payload.job ?? payload.data?.job ?? payload.data ?? {};
+        const state = job.state ?? 'unknown';
+        const score = scoreFromPayload(payload);
+        const lines = [
+            `Rubrkit ${payload.command} remote ${state}`,
+            `Job: ${job.id ?? payload.jobId ?? '(unknown)'}`,
+        ];
+
+        if (job.phase || job.message) {
+            lines.push(`Latest: ${[job.phase, job.message].filter(Boolean).join(' - ')}`);
+        }
+
+        if (typeof score === 'number') {
+            lines.push(`Score: ${score}`);
+        }
+
+        if (job.error?.message) {
+            lines.push(`Error: ${job.error.code ?? 'job_failed'} - ${job.error.message}`);
+        }
+
+        return `${lines.join('\n')}\n`;
+    }
+
+    if (payload.mode === 'report') {
+        const job = payload.job ?? payload.data?.job ?? payload;
+        return [
+            `Rubrkit report ${job.state ?? 'unknown'}`,
+            `Job: ${job.id ?? payload.id ?? '(unknown)'}`,
+            `Kind: ${job.kind ?? '(unknown)'}`,
+            `Latest: ${[job.phase, job.message].filter(Boolean).join(' - ') || '(none)'}`,
+        ].join('\n') + '\n';
+    }
+
+    const summary = payload.summary ?? {};
+    const status = payload.passed ? 'PASS' : 'FAIL';
+    const lines = [
+        `Rubrkit ${payload.command ?? 'validate'} ${payload.mode ?? 'local'}`,
+        `${status} ${payload.target ?? ''} (${summary.fileCount ?? 0} files, ${summary.errorCount ?? 0} errors, ${summary.warningCount ?? 0} warnings, score ${summary.score ?? 0})`,
+    ];
+
+    for (const file of payload.files ?? []) {
+        lines.push(`- ${file.passed ? 'PASS' : 'FAIL'} ${file.path}`);
+
+        for (const issue of file.issues ?? []) {
+            const location = issue.line ? ` line ${issue.line}${issue.column ? `:${issue.column}` : ''}` : '';
+            lines.push(`  ${issue.severity.toUpperCase()} ${issue.code}${location}: ${issue.message}`);
+            lines.push(`    fix: ${issue.fix}`);
+        }
+    }
+
+    for (const gate of payload.gates?.failures ?? []) {
+        lines.push(`Gate ${gate.code}: ${gate.message}`);
+    }
+
+    return `${lines.join('\n')}\n`;
+}
+
+/**
+ * @param {Record<string, any>} payload
+ */
+function renderJUnit(payload) {
+    const files = Array.isArray(payload.files) ? payload.files : [];
+    const tests = files.length || 1;
+    const failures = files.reduce((sum, file) => sum + Number(file.errorCount ?? 0), 0);
+    const warnings = files.reduce((sum, file) => sum + Number(file.warningCount ?? 0), 0);
+    const name = `rubrkit.${payload.command ?? 'test'}.${payload.mode ?? 'local'}`;
+    const testcases = files.length > 0 ? files.map(renderFileTestCase).join('\n') : renderRemoteTestCase(payload);
+
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuite name="${xml(name)}" tests="${tests}" failures="${failures}" errors="0" skipped="0">`,
+        warnings > 0 ? `  <system-out>${xml(`${warnings} Rubrkit warning${warnings === 1 ? '' : 's'}`)}</system-out>` : '',
+        testcases,
+        '</testsuite>',
+        '',
+    ].filter(line => line !== '').join('\n');
+}
+
+/**
+ * @param {Record<string, any>} file
+ */
+function renderFileTestCase(file) {
+    const failures = (file.issues ?? []).filter(issue => issue.severity === 'error');
+    const warnings = (file.issues ?? []).filter(issue => issue.severity === 'warning');
+    const body = [];
+
+    if (failures.length > 0) {
+        body.push(
+            `    <failure message="${xml(`${failures.length} Rubrkit validation error${failures.length === 1 ? '' : 's'}`)}">${xml(
+                failures.map(formatIssue).join('\n'),
+            )}</failure>`,
+        );
+    }
+
+    if (warnings.length > 0) {
+        body.push(`    <system-out>${xml(warnings.map(formatIssue).join('\n'))}</system-out>`);
+    }
+
+    if (body.length === 0) {
+        return `  <testcase name="${xml(file.path)}" classname="RubrkitLocalChecks" />`;
+    }
+
+    return [`  <testcase name="${xml(file.path)}" classname="RubrkitLocalChecks">`, ...body, '  </testcase>'].join('\n');
+}
+
+/**
+ * @param {Record<string, any>} payload
+ */
+function renderRemoteTestCase(payload) {
+    const job = payload.job ?? {};
+    const failed = ['failed', 'cancelled', 'paused'].includes(job.state);
+
+    if (!failed) {
+        return `  <testcase name="${xml(job.id ?? payload.jobId ?? 'remote-job')}" classname="RubrkitRemoteJob" />`;
+    }
+
+    return [
+        `  <testcase name="${xml(job.id ?? payload.jobId ?? 'remote-job')}" classname="RubrkitRemoteJob">`,
+        `    <failure message="${xml(job.error?.message ?? 'Remote Rubrkit job did not succeed.')}">${xml(JSON.stringify(job.error ?? {}, null, 2))}</failure>`,
+        '  </testcase>',
+    ].join('\n');
+}
+
+/**
+ * @param {Record<string, any>} issue
+ */
+function formatIssue(issue) {
+    const location = issue.line ? `line ${issue.line}${issue.column ? `:${issue.column}` : ''}` : 'file';
+    return `${location} ${issue.severity?.toUpperCase?.() ?? 'ISSUE'} ${issue.code}: ${issue.message}\nfix: ${issue.fix}`;
+}
+
+/**
+ * @param {string} value
+ */
+function xml(value) {
+    return String(value)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+
+/**
+ * @param {Record<string, any>} payload
+ */
+export function scoreFromPayload(payload) {
+    const candidates = [
+        payload.summary?.score,
+        payload.job?.result?.overallScore,
+        payload.job?.result?.score,
+        payload.started?.auditRun?.result?.overallScore,
+        payload.started?.auditRun?.summary?.overallScore,
+        payload.started?.evalRun?.summary?.score,
+        payload.started?.result?.overallScore,
+    ];
+
+    for (const candidate of candidates) {
+        const value = Number(candidate);
+        if (Number.isFinite(value)) {
+            return value;
+        }
+    }
+
+    return null;
+}

package/src/index.d.ts

@@ -0,0 +1,76 @@
+export interface RubrkitOptions {
+  apiKey?: string | null;
+  apiUrl?: string;
+  fetchImpl?: typeof fetch;
+  userAgent?: string;
+  retryReads?: number;
+}
+
+export interface JobWaitOptions {
+  intervalMs?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  onProgress?: (job: Record<string, unknown>) => void;
+}
+
+export class RubrkitError extends Error {
+  code: string;
+  details?: unknown;
+}
+
+export class RubrkitApiError extends RubrkitError {
+  status: number;
+  requestId: string | null;
+}
+
+export class RubrkitNetworkError extends RubrkitError {}
+
+export class Rubrkit {
+  constructor(options?: RubrkitOptions);
+
+  me: {
+    get(): Promise<Record<string, unknown>>;
+  };
+
+  artifactBundles: {
+    list(params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    create(params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    get(id: string): Promise<Record<string, unknown>>;
+  };
+
+  artifacts: {
+    list(params: { artifactBundleId: string } & Record<string, unknown>): Promise<Record<string, unknown>>;
+    pull(params: { artifactBundleId: string; artifactId?: string; fileId?: string } & Record<string, unknown>): Promise<Record<string, unknown>>;
+    upload(params: { artifactBundleId: string; files: Array<Record<string, unknown>> } & Record<string, unknown>): Promise<Record<string, unknown>>;
+    test(params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  };
+
+  audits: {
+    run(params: { artifactBundleId: string } & Record<string, unknown>): Promise<Record<string, unknown>>;
+  };
+
+  evals: {
+    run(params: { artifactBundleId: string } & Record<string, unknown>): Promise<Record<string, unknown>>;
+  };
+
+  rubrFlow: {
+    convert(params: { artifactBundleId: string } & Record<string, unknown>): Promise<Record<string, unknown>>;
+  };
+
+  jobs: {
+    get(id: string): Promise<Record<string, unknown>>;
+    wait(id: string, options?: JobWaitOptions): Promise<Record<string, unknown>>;
+  };
+
+  proofReports: {
+    get(id: string, options: { artifactBundleId: string }): Promise<Record<string, unknown>>;
+    get(params: { artifactBundleId: string; proofReportId: string }): Promise<Record<string, unknown>>;
+  };
+
+  request(path: string, options?: {
+    method?: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    signal?: AbortSignal;
+  }): Promise<Record<string, unknown>>;
+}