rubrkit 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# Rubrkit CLI
+
+Local v1 package for pulling Rubrkit artifact-bundle files into agent projects and testing artifacts from local projects or CI.
+
+The package folder is `tools/rubrkit-cli`, but the intended published package name and executable are `rubrkit` so users can run:
+
+```bash
+npx rubrkit pull [all|<artifact-bundle-or-artifact-selector>]
+npx rubrkit validate <path|glob>
+npx rubrkit test <path|glob|artifact-bundle-or-artifact-selector>
+npx rubrkit audit <artifact-bundle-or-selector>
+npx rubrkit eval <artifact-bundle-or-selector>
+npx rubrkit report <job-or-run-id>
+```
+
+## Auth
+
+Use a Rubrkit API key for pull commands and remote checks. Prefer a pull key scoped to `artifacts:pull`. For `rubrkit test <path> --remote`, use a testing key scoped to the existing composed API flow: `artifact_bundles:write`, `files:write`, `audits:run`, `jobs:read`, and `credits:read`.
+
+```bash
+RUBRKIT_API_KEY=... rubrkit pull all --yes
+```
+
+`--api-key` is also supported for secret-manager wrappers. API keys are never written to `.rubrkit/manifest.json`, local reports, fixtures, or snapshots.
+
+## Pull Examples
+
+```bash
+rubrkit pull
+rubrkit pull all --yes
+rubrkit pull team-agent-kit --destination .
+rubrkit pull --artifact-bundle team-agent-kit --artifact AGENTS.md --yes
+rubrkit pull all --yes --dry-run
+```
+
+Useful flags:
+
+```text
+--destination <path>
+--agent <auto|codex|claude|generic>
+--artifact-bundle <id-or-name>
+--artifact <id-or-path>
+--rubric <rubric-id-or-path>
+--format <text|json|junit>
+--output <path>
+--fail-under <score>
+--fail-on <critical|high|medium|low>
+--ci
+--local
+--remote
+--no-ai
+--watch
+--changed
+--all
+--yes
+--dry-run
+--force
+--prune
+--update-only
+--config <path>
+--api-url <url>
+--api-key <key>
+```
+
+## Testing Examples
+
+Local validation runs without network access or credits where possible:
+
+```bash
+rubrkit validate docs/example.rubr_flow
+rubrkit test "prompts/**/*.md" --local --format json
+```
+
+Remote checks use the public `/api/v1` API, create async jobs, and poll `/jobs/{jobId}`. Local-file remote tests create or select an artifact bundle, upload the local text files, then start an audit job:
+
+```bash
+RUBRKIT_API_KEY=... rubrkit test team-agent-kit --remote --format json
+RUBRKIT_API_KEY=... rubrkit audit team-agent-kit --fail-under 85 --ci
+RUBRKIT_API_KEY=... rubrkit eval team-agent-kit --format junit --output rubrkit-junit.xml
+RUBRKIT_API_KEY=... rubrkit report <job-id>
+```
+
+Use `--dry-run --remote` to inspect the remote request shape without calling the API.
+
+Exit codes:
+
+- `0`: checks passed.
+- `1`: checks completed and failed validation or quality gates.
+- `2`: invalid CLI usage or invalid config.
+- `3`: authentication or authorization failure.
+- `4`: credit, usage-limit, or circuit-breaker block.
+- `5`: network, provider, or server failure.
+
+## SDK
+
+The current local package exports the SDK from `rubrkit` while final package naming awaits owner approval.
+
+```js
+import { Rubrkit } from 'rubrkit';
+
+const client = new Rubrkit({ apiKey: process.env.RUBRKIT_API_KEY });
+const started = await client.artifacts.test({ artifactBundleId: 'team-agent-kit' });
+const job = await client.jobs.wait(started.jobId);
+```
+
+## Placement
+
+- Codex primary artifacts are placed as `AGENTS.md`; supporting files go under `.rubrkit/artifacts/<bundle>/`.
+- Claude primary artifacts are placed as `CLAUDE.md`, or `.claude/CLAUDE.md` when that file already exists; supporting files go under `.rubrkit/artifacts/<bundle>/`.
+- Generic placement preserves artifact paths under `.rubrkit/artifacts/<bundle>/`.
+
+The CLI protects existing local files unless they were previously managed by Rubrkit and match the local manifest. Use `--force` to overwrite after reviewing the plan.
+
+## Postinstall
+
+Rubrkit does not run network sync from its own package lifecycle. Consuming projects can opt in:
+
+```json
+{
+  "scripts": {
+    "postinstall": "rubrkit pull all --yes"
+  }
+}
+```
+
+Postinstall commands should use `RUBRKIT_API_KEY` and an unambiguous selector.

package/bin/rubrkit.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.js';
+
+const exitCode = await main({
+    argv: process.argv.slice(2),
+    env: process.env,
+    cwd: process.cwd(),
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+});
+
+if (exitCode !== 0) {
+    process.exitCode = exitCode;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "rubrkit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Rubrkit CLI for pulling artifact bundles into local agent projects.",
+  "bin": {
+    "rubrkit": "./bin/rubrkit.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/sdk.js"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  }
+}

package/src/adapters.js

@@ -0,0 +1,118 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { normalizeArtifactPath, slugifyPathSegment } from './pathSafety.js';
+
+const CODEX_SIGNALS = ['AGENTS.override.md', 'AGENTS.md', '.codex/config.toml'];
+const CLAUDE_SIGNALS = ['CLAUDE.md', '.claude/CLAUDE.md', '.claude/settings.json', '.claude/settings.local.json'];
+
+/**
+ * @param {{ root: string, requestedAgent?: string, fsImpl?: Pick<typeof fs, 'existsSync'> }} params
+ */
+export function resolveAgentAdapter({ root, requestedAgent = 'auto', fsImpl = fs }) {
+    const agent = requestedAgent === 'auto' ? detectAgent(root, fsImpl) : requestedAgent;
+
+    if (agent === 'codex') return codexAdapter;
+    if (agent === 'claude') return claudeAdapter;
+
+    return genericAdapter;
+}
+
+/**
+ * @param {string} root
+ * @param {Pick<typeof fs, 'existsSync'>} fsImpl
+ */
+export function detectAgent(root, fsImpl = fs) {
+    if (CODEX_SIGNALS.some((signal) => fsImpl.existsSync(path.join(root, signal)))) {
+        return 'codex';
+    }
+
+    if (CLAUDE_SIGNALS.some((signal) => fsImpl.existsSync(path.join(root, signal)))) {
+        return 'claude';
+    }
+
+    return 'generic';
+}
+
+export const genericAdapter = {
+    name: 'generic',
+    detectionSignals: [],
+    supportedArtifactTypes: ['agent', 'command', 'markdown', 'prompt', 'rubr_flow', 'skill', 'text', 'workflow'],
+    /**
+     * @param {PlacementInput} input
+     */
+    place(input) {
+        return placeSupportingArtifact(input);
+    },
+};
+
+export const codexAdapter = {
+    name: 'codex',
+    detectionSignals: CODEX_SIGNALS,
+    supportedArtifactTypes: ['agent', 'command', 'markdown', 'prompt', 'rubr_flow', 'skill', 'text', 'workflow'],
+    /**
+     * @param {PlacementInput} input
+     */
+    place(input) {
+        const basename = path.posix.basename(normalizeArtifactPath(input.file.path));
+
+        if (basename === 'AGENTS.md' || basename === 'AGENTS.override.md') {
+            return { destinationPath: basename, reason: 'Codex project instruction file' };
+        }
+
+        if (input.file.isPrimary) {
+            return { destinationPath: 'AGENTS.md', reason: 'Codex primary artifact placement' };
+        }
+
+        return placeSupportingArtifact(input);
+    },
+};
+
+export const claudeAdapter = {
+    name: 'claude',
+    detectionSignals: CLAUDE_SIGNALS,
+    supportedArtifactTypes: ['agent', 'command', 'markdown', 'prompt', 'rubr_flow', 'skill', 'text', 'workflow'],
+    /**
+     * @param {PlacementInput} input
+     */
+    place(input) {
+        const normalizedPath = normalizeArtifactPath(input.file.path);
+        const basename = path.posix.basename(normalizedPath);
+
+        if (basename === 'CLAUDE.md' || basename === 'CLAUDE.local.md') {
+            return { destinationPath: basename, reason: 'Claude Code project instruction file' };
+        }
+
+        if (input.file.isPrimary) {
+            const existingDotClaude = input.exists('.claude/CLAUDE.md');
+
+            return {
+                destinationPath: existingDotClaude ? '.claude/CLAUDE.md' : 'CLAUDE.md',
+                reason: 'Claude Code primary artifact placement',
+            };
+        }
+
+        return placeSupportingArtifact(input);
+    },
+};
+
+/**
+ * @param {PlacementInput} input
+ */
+function placeSupportingArtifact(input) {
+    const bundleSegment = slugifyPathSegment(input.artifactBundle.name ?? input.artifactBundle.id);
+    const artifactPath = normalizeArtifactPath(input.file.path);
+
+    return {
+        destinationPath: `.rubrkit/artifacts/${bundleSegment}/${artifactPath}`,
+        reason: 'Generic supporting artifact placement',
+    };
+}
+
+/**
+ * @typedef {{
+ *   artifactBundle: Record<string, any>,
+ *   file: Record<string, any>,
+ *   exists(relativePath: string): boolean,
+ * }} PlacementInput
+ */

package/src/api.js

@@ -0,0 +1,101 @@
+import { exitCodeForApiFailure, RubrkitCliError } from './errors.js';
+
+export class RubrkitApiClient {
+    /**
+     * @param {{ apiUrl: string, apiKey: string, fetchImpl?: typeof fetch }} options
+     */
+    constructor({ apiUrl, apiKey, fetchImpl = globalThis.fetch }) {
+        this.apiUrl = apiUrl.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+    }
+
+    async listArtifactBundles() {
+        const data = await this.request('/artifact-bundles?status=active&limit=100');
+        return Array.isArray(data.artifactBundles) ? data.artifactBundles : [];
+    }
+
+    /**
+     * @param {string} artifactBundleId
+     */
+    async getArtifactBundle(artifactBundleId) {
+        const data = await this.request(`/artifact-bundles/${encodeURIComponent(artifactBundleId)}`);
+        return data;
+    }
+
+    /**
+     * @param {string} artifactBundleId
+     */
+    async listFiles(artifactBundleId) {
+        const data = await this.request(`/artifact-bundles/${encodeURIComponent(artifactBundleId)}/files?limit=200`);
+        return Array.isArray(data.files) ? data.files : [];
+    }
+
+    /**
+     * @param {string} artifactBundleId
+     * @param {string} fileId
+     */
+    async getFile(artifactBundleId, fileId) {
+        return this.request(`/artifact-bundles/${encodeURIComponent(artifactBundleId)}/files/${encodeURIComponent(fileId)}`);
+    }
+
+    /**
+     * @param {string} path
+     */
+    /**
+     * @param {string} path
+     * @param {{ method?: string, body?: unknown }} [options]
+     */
+    async request(path, { method = 'GET', body: requestBody = undefined } = {}) {
+        /** @type {Record<string, string>} */
+        const headers = {
+            accept: 'application/json',
+            authorization: `Bearer ${this.apiKey}`,
+            'user-agent': 'rubrkit-cli/0.0.0-local',
+        };
+
+        if (requestBody !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+
+        const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+            method,
+            headers,
+            body: requestBody === undefined ? undefined : JSON.stringify(requestBody),
+        });
+
+        const text = await response.text();
+        const body = text ? parseJson(text) : {};
+
+        if (!response.ok) {
+            const error = body && typeof body === 'object' && 'error' in body ? body.error : {};
+            const message =
+                error && typeof error === 'object' && typeof error.message === 'string'
+                    ? error.message
+                    : `Rubrkit API request failed with HTTP ${response.status}.`;
+            const code = error && typeof error === 'object' && typeof error.code === 'string' ? error.code : 'api_request_failed';
+
+            throw new RubrkitCliError(message, {
+                code,
+                exitCode: exitCodeForApiFailure(code, response.status),
+            });
+        }
+
+        return body && typeof body === 'object' && 'data' in body ? body.data : body;
+    }
+}
+
+/**
+ * @param {string} text
+ */
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    } catch (error) {
+        throw new RubrkitCliError('Rubrkit API returned invalid JSON.', {
+            code: 'invalid_api_response',
+            exitCode: 1,
+            details: error,
+        });
+    }
+}

package/src/args.js

@@ -0,0 +1,175 @@
+import { usageError } from './errors.js';
+
+const VALUE_FLAGS = new Set([
+    'destination',
+    'agent',
+    'artifact-bundle',
+    'artifact',
+    'rubric',
+    'format',
+    'output',
+    'fail-under',
+    'fail-on',
+    'config',
+    'api-url',
+    'api-key',
+]);
+
+const BOOLEAN_FLAGS = new Set([
+    'all',
+    'yes',
+    'dry-run',
+    'force',
+    'prune',
+    'update-only',
+    'ci',
+    'local',
+    'remote',
+    'no-ai',
+    'watch',
+    'changed',
+    'help',
+    'version',
+]);
+
+const AGENTS = new Set(['auto', 'codex', 'claude', 'generic']);
+const COMMANDS = new Set(['pull', 'validate', 'test', 'audit', 'eval', 'report']);
+const FORMATS = new Set(['text', 'json', 'junit']);
+const FAIL_ON_LEVELS = new Set(['critical', 'high', 'medium', 'low']);
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+    const [command, ...rest] = argv;
+
+    if (!command || command === '--help' || command === '-h') {
+        return { command: command ? 'help' : 'help', selector: null, options: {} };
+    }
+
+    if (command === '--version' || command === '-v') {
+        return { command: 'version', selector: null, options: {} };
+    }
+
+    if (!COMMANDS.has(command)) {
+        throw usageError(`Unknown command "${command}". Run rubrkit --help for usage.`);
+    }
+
+    /** @type {Record<string, string | boolean>} */
+    const options = {};
+    /** @type {string[]} */
+    const positionals = [];
+
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+
+        if (arg === '--') {
+            positionals.push(...rest.slice(index + 1));
+            break;
+        }
+
+        if (!arg.startsWith('-') || arg === '-') {
+            positionals.push(arg);
+            continue;
+        }
+
+        const normalized = normalizeFlag(arg);
+
+        if (normalized.alias) {
+            options[normalized.name] = true;
+            continue;
+        }
+
+        if (BOOLEAN_FLAGS.has(normalized.name)) {
+            if (normalized.value !== null) {
+                throw usageError(`Flag --${normalized.name} does not accept a value.`);
+            }
+
+            options[normalized.name] = true;
+            continue;
+        }
+
+        if (VALUE_FLAGS.has(normalized.name)) {
+            const value = normalized.value ?? rest[index + 1];
+
+            if (!value || value.startsWith('--')) {
+                throw usageError(`Flag --${normalized.name} requires a value.`);
+            }
+
+            options[normalized.name] = value;
+
+            if (normalized.value === null) {
+                index += 1;
+            }
+
+            continue;
+        }
+
+        throw usageError(`Unknown flag --${normalized.name}.`);
+    }
+
+    if (positionals.length > 1) {
+        throw usageError(`The ${command} command accepts at most one target or selector.`);
+    }
+
+    const selector = positionals[0] ?? null;
+
+    if (selector === 'all') {
+        options.all = true;
+    }
+
+    if (typeof options.agent === 'string' && !AGENTS.has(options.agent)) {
+        throw usageError('--agent must be one of auto, codex, claude, or generic.');
+    }
+
+    if (typeof options.format === 'string' && !FORMATS.has(options.format)) {
+        throw usageError('--format must be one of text, json, or junit.');
+    }
+
+    if (typeof options['fail-on'] === 'string' && !FAIL_ON_LEVELS.has(options['fail-on'])) {
+        throw usageError('--fail-on must be one of critical, high, medium, or low.');
+    }
+
+    if (options['fail-under'] !== undefined) {
+        const value = Number(options['fail-under']);
+        if (!Number.isFinite(value) || value < 0 || value > 100) {
+            throw usageError('--fail-under must be a number from 0 to 100.');
+        }
+    }
+
+    if (options.local && options.remote) {
+        throw usageError('Use either --local or --remote, not both.');
+    }
+
+    return { command, selector, options };
+}
+
+/**
+ * @param {string} arg
+ */
+function normalizeFlag(arg) {
+    if (arg === '-y') {
+        return { name: 'yes', value: null, alias: true };
+    }
+
+    if (arg === '-h') {
+        return { name: 'help', value: null, alias: true };
+    }
+
+    if (!arg.startsWith('--')) {
+        throw usageError(`Unknown short flag "${arg}".`);
+    }
+
+    const raw = arg.slice(2);
+    const equalsIndex = raw.indexOf('=');
+
+    if (equalsIndex === -1) {
+        return { name: raw, value: null, alias: false };
+    }
+
+    return {
+        name: raw.slice(0, equalsIndex),
+        value: raw.slice(equalsIndex + 1),
+        alias: false,
+    };
+}

package/src/cli.js

@@ -0,0 +1,93 @@
+import { parseArgs } from './args.js';
+import { resolveConfig } from './config.js';
+import { RubrkitCliError } from './errors.js';
+import { runPull } from './pull.js';
+import { runTestingCommand } from './testingCli.js';
+
+const HELP_TEXT = `Rubrkit CLI
+
+Usage:
+  rubrkit pull [all|<artifact-bundle-or-artifact-selector>] [options]
+  rubrkit validate <path|glob> [options]
+  rubrkit test <path|glob|artifact-bundle-or-artifact-selector> [options]
+  rubrkit audit <artifact-bundle-or-selector> [options]
+  rubrkit eval <artifact-bundle-or-selector> [options]
+  rubrkit report <job-or-run-id> [options]
+
+Options:
+  --destination <path>       Destination root. Defaults to the current directory.
+  --agent <auto|codex|claude|generic>
+  --artifact-bundle <id-or-name>
+  --artifact <id-or-path>
+  --rubric <rubric-id-or-path>
+  --format <text|json|junit>
+  --output <path>
+  --fail-under <score>
+  --fail-on <critical|high|medium|low>
+  --ci
+  --local
+  --remote
+  --no-ai
+  --watch
+  --changed
+  --all
+  --yes                     Non-interactive confirmation for unambiguous pulls.
+  --dry-run                 Print the planned writes without changing files.
+  --force                   Overwrite protected local changes.
+  --prune                   Remove manifest-tracked files no longer selected.
+  --update-only             Update only files already tracked in .rubrkit/manifest.json.
+  --config <path>           Optional Rubrkit config JSON. API keys are not allowed in config.
+  --api-url <url>           Defaults to RUBRKIT_API_URL or https://rubrkit.com/api/v1.
+  --api-key <key>           Defaults to RUBRKIT_API_KEY.
+`;
+
+/**
+ * @param {{
+ *   argv?: string[],
+ *   env?: Record<string, string | undefined>,
+ *   cwd?: string,
+ *   stdin?: NodeJS.ReadableStream,
+ *   stdout?: NodeJS.WritableStream,
+ *   stderr?: NodeJS.WritableStream,
+ *   fetchImpl?: typeof fetch,
+ * }} [params]
+ */
+export async function main({
+    argv = process.argv.slice(2),
+    env = process.env,
+    cwd = process.cwd(),
+    stdin = process.stdin,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    fetchImpl = globalThis.fetch,
+} = {}) {
+    try {
+        const parsed = parseArgs(argv);
+
+        if (parsed.command === 'help') {
+            stdout.write(HELP_TEXT);
+            return 0;
+        }
+
+        if (parsed.command === 'version') {
+            stdout.write('rubrkit 0.0.0-local\n');
+            return 0;
+        }
+
+        const config = await resolveConfig({ parsed, env, cwd });
+        if (parsed.command === 'pull') {
+            await runPull({ config, stdin, stdout, stderr, fetchImpl });
+            return 0;
+        }
+
+        return runTestingCommand({ config, stdout, stderr, fetchImpl });
+    } catch (error) {
+        if (error instanceof RubrkitCliError) {
+            stderr.write(`rubrkit: ${error.message}\n`);
+            return error.exitCode;
+        }
+
+        stderr.write(`rubrkit: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}