@myclaw163/clawclaw-cli 0.6.54

package/src/lib/host-config-patcher.test.ts

@@ -0,0 +1,130 @@
+import { mkdtempSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { dirname, join } from 'path';
+import { describe, expect, it } from 'vitest';
+import { runHostConfigSetup, unionArrayField, type HostConfigPatcher } from './host-config-patcher.js';
+
+function tmpConfig(initial: unknown): string {
+  const dir = mkdtempSync(join(tmpdir(), 'host-cfg-'));
+  const p = join(dir, 'config.json');
+  writeFileSync(p, JSON.stringify(initial, null, 2));
+  return p;
+}
+
+const dummyHost: HostConfigPatcher<{ value: string }> = {
+  hostName: 'dummy',
+  resolveConfigPath: () => '/tmp/never-used',
+  computePatch: (current, opts) => {
+    const cur = (current as Record<string, unknown> | null) ?? {};
+    const before = (cur.values as string[] | undefined) ?? [];
+    if (before.includes(opts.value)) return { next: cur, changes: [], warnings: [] };
+    return {
+      next: { ...cur, values: [...before, opts.value] },
+      changes: [`add ${opts.value} to values`],
+      warnings: [],
+    };
+  },
+};
+
+describe('runHostConfigSetup', () => {
+  it('prints recommended patch in --print mode without touching disk', () => {
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { print: true });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.join('\n')).toContain('"values"');
+  });
+
+  it('reports missing config file gracefully', () => {
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: '/no/such/file.json' });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.some((l) => l.includes('not found'))).toBe(true);
+  });
+
+  it('reports malformed JSON with exit 1', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-bad-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{ not: valid json');
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: p });
+    expect(r.exitCode).toBe(1);
+    expect(r.output.join('\n')).toMatch(/Failed to parse/);
+  });
+
+  it('returns exit 2 with diff in dry-run when changes pending', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p });
+    expect(r.exitCode).toBe(2);
+    const txt = r.output.join('\n');
+    expect(txt).toMatch(/Pending changes/);
+    expect(txt).toMatch(/Re-run with -y to apply/);
+    // file unchanged
+    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a'] });
+  });
+
+  it('returns exit 0 no-op when already up to date', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'a' }, { configPath: p });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.join('\n')).toMatch(/already up to date/);
+  });
+
+  it('applies changes atomically with backup when -y', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true });
+    expect(r.exitCode).toBe(0);
+    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a', 'b'] });
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(true);
+  });
+
+  it('--no-backup skips backup file', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    expect(r.exitCode).toBe(0);
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(false);
+  });
+
+  it('does not leave .tmp file behind on success', () => {
+    const p = tmpConfig({ values: ['a'] });
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.includes('.tmp.'))).toBe(false);
+  });
+
+  it('preserves CRLF line endings when original file uses CRLF', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-crlf-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{\r\n  "values": [\r\n    "a"\r\n  ]\r\n}\r\n');
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const after = readFileSync(p, 'utf-8');
+    expect(after.includes('\r\n')).toBe(true);
+    expect(after.replace(/\r\n/g, '<EOL>').includes('\n')).toBe(false);
+  });
+
+  it('preserves LF line endings when original file uses LF', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-lf-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{\n  "values": [\n    "a"\n  ]\n}\n');
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const after = readFileSync(p, 'utf-8');
+    expect(after.includes('\r\n')).toBe(false);
+  });
+});
+
+describe('unionArrayField', () => {
+  it('creates new array when field missing', () => {
+    expect(unionArrayField(undefined, 'x')).toEqual({ next: ['x'], added: true });
+  });
+
+  it('returns warning when existing value is not an array', () => {
+    const r = unionArrayField('not-an-array', 'x');
+    expect(r).toEqual({ warning: 'existing value is not an array, refusing to overwrite' });
+  });
+
+  it('returns added=false when entry already present', () => {
+    expect(unionArrayField(['a', 'b'], 'a')).toEqual({ next: ['a', 'b'], added: false });
+  });
+
+  it('appends entry when missing from array', () => {
+    expect(unionArrayField(['a'], 'b')).toEqual({ next: ['a', 'b'], added: true });
+  });
+});

package/src/lib/host-config-patcher.ts

@@ -0,0 +1,151 @@
+/**
+ * Generic JSON-config setup runner shared by `ccl setup <host>` subcommands.
+ *
+ * Each host adapter only supplies:
+ *   - resolveConfigPath(): where the host stores its global JSON config
+ *   - computePatch(current, opts): pure function returning the desired next config + change/warning notes
+ *
+ * The runner handles dry-run, diff, atomic write, and timestamped backup uniformly,
+ * so adding a new host (gemini, claude-code, ...) is ~30 lines of glue.
+ */
+
+import { existsSync, readFileSync, renameSync, copyFileSync, writeFileSync } from 'fs';
+
+export interface HostConfigPatcher<Opts extends object = Record<string, never>> {
+  hostName: string;
+  resolveConfigPath: () => string;
+  computePatch: (current: unknown, opts: Opts) => HostPatchResult;
+}
+
+export interface HostPatchResult {
+  next: unknown;
+  changes: string[];
+  warnings: string[];
+}
+
+export interface RunHostSetupFlags {
+  yes?: boolean;
+  print?: boolean;
+  configPath?: string;
+  backup?: boolean;
+}
+
+export interface RunHostSetupResult {
+  exitCode: number;
+  output: string[];
+}
+
+export function runHostConfigSetup<Opts extends object>(
+  patcher: HostConfigPatcher<Opts>,
+  hostOpts: Opts,
+  flags: RunHostSetupFlags,
+): RunHostSetupResult {
+  const out: string[] = [];
+  const configPath = flags.configPath ?? patcher.resolveConfigPath();
+
+  if (flags.print) {
+    const sample = patcher.computePatch({}, hostOpts);
+    out.push(`# Recommended ${patcher.hostName} config patch:`);
+    out.push(JSON.stringify(sample.next, null, 2));
+    return { exitCode: 0, output: out };
+  }
+
+  if (!existsSync(configPath)) {
+    out.push(`${patcher.hostName} config not found at: ${configPath}`);
+    out.push(`Initialize it first (e.g. \`openclaw doctor\` for OpenClaw), then re-run.`);
+    return { exitCode: 0, output: out };
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, 'utf-8');
+  } catch (err: any) {
+    out.push(`Failed to read ${configPath}: ${err?.message ?? err}`);
+    return { exitCode: 1, output: out };
+  }
+
+  let current: unknown;
+  try {
+    current = JSON.parse(raw);
+  } catch (err: any) {
+    out.push(`Failed to parse JSON at ${configPath}: ${err?.message ?? err}`);
+    out.push(`Fix the JSON manually first; this tool does not edit malformed files.`);
+    return { exitCode: 1, output: out };
+  }
+
+  const { next, changes, warnings } = patcher.computePatch(current, hostOpts);
+
+  for (const w of warnings) out.push(`warning: ${w}`);
+
+  if (changes.length === 0) {
+    out.push(`${patcher.hostName} config already up to date at ${configPath}.`);
+    return { exitCode: 0, output: out };
+  }
+
+  if (!flags.yes) {
+    out.push(`Pending changes to ${configPath}:`);
+    for (const c of changes) out.push(`  - ${c}`);
+    out.push(``);
+    out.push(diffJson(current, next));
+    out.push(``);
+    out.push(`Dry-run only. Re-run with -y to apply.`);
+    return { exitCode: 2, output: out };
+  }
+
+  let backupPath: string | undefined;
+  if (flags.backup !== false) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    backupPath = `${configPath}.bak.${ts}`;
+    try {
+      copyFileSync(configPath, backupPath);
+    } catch (err: any) {
+      out.push(`Failed to back up ${configPath} → ${backupPath}: ${err?.message ?? err}`);
+      return { exitCode: 1, output: out };
+    }
+  }
+
+  const tmpPath = `${configPath}.tmp.${process.pid}`;
+  try {
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    const serialized = JSON.stringify(next, null, 2).replace(/\n/g, eol) + eol;
+    writeFileSync(tmpPath, serialized, 'utf-8');
+    renameSync(tmpPath, configPath);
+  } catch (err: any) {
+    out.push(`Failed to write ${configPath}: ${err?.message ?? err}`);
+    return { exitCode: 1, output: out };
+  }
+
+  out.push(`Updated ${configPath}:`);
+  for (const c of changes) out.push(`  - ${c}`);
+  if (backupPath) out.push(`Backup: ${backupPath}`);
+  return { exitCode: 0, output: out };
+}
+
+/** Minimal line-level JSON diff for the dry-run preview. Self-contained, zero deps. */
+export function diffJson(before: unknown, after: unknown): string {
+  const a = JSON.stringify(before, null, 2).split('\n');
+  const b = JSON.stringify(after, null, 2).split('\n');
+  const aSet = new Set(a);
+  const bSet = new Set(b);
+  const lines: string[] = [];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i++) {
+    const ax = a[i];
+    const bx = b[i];
+    if (ax === bx) {
+      lines.push(`  ${ax ?? ''}`);
+    } else {
+      if (ax !== undefined && !bSet.has(ax)) lines.push(`- ${ax}`);
+      if (bx !== undefined && !aSet.has(bx)) lines.push(`+ ${bx}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** Shared helper for hosts: add an entry to an array field, returning a new array (Set union). */
+export function unionArrayField(arr: unknown, entry: string): { next: string[]; added: boolean } | { warning: string } {
+  if (arr === undefined) return { next: [entry], added: true };
+  if (!Array.isArray(arr)) return { warning: `existing value is not an array, refusing to overwrite` };
+  if (arr.includes(entry)) return { next: arr.slice() as string[], added: false };
+  return { next: [...(arr as string[]), entry], added: true };
+}

package/src/lib/http-keepalive.ts

@@ -0,0 +1,15 @@
+import { Agent, setGlobalDispatcher } from 'undici';
+
+let initialized = false;
+
+export function initHttpKeepAlive(): void {
+  if (initialized) return;
+  initialized = true;
+
+  setGlobalDispatcher(new Agent({
+    keepAliveTimeout: 30_000,
+    keepAliveMaxTimeout: 120_000,
+    connections: 16,
+    pipelining: 1,
+  }));
+}

package/src/lib/http-transport.test.ts

@@ -0,0 +1,42 @@
+// src/lib/http-transport.test.ts
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { HttpTransport, ApiError } from './http-transport.js';
+
+const registry: any = { baseUrlFor: () => 'https://hub.example' };
+
+afterEach(() => { vi.restoreAllMocks(); });
+
+describe('HttpTransport.getBytes', () => {
+  it('returns response bytes as a Buffer', async () => {
+    const bytes = new Uint8Array([1, 2, 3, 4]);
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(bytes, { status: 200 })));
+    const t = new HttpTransport('key', registry);
+    const buf = await t.getBytes('/api/v1/hub/x');
+    expect(Buffer.isBuffer(buf)).toBe(true);
+    expect([...buf]).toEqual([1, 2, 3, 4]);
+  });
+
+  it('throws ApiError on non-ok', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('nope', { status: 404 })));
+    const t = new HttpTransport('key', registry);
+    await expect(t.getBytes('/api/v1/hub/x')).rejects.toBeInstanceOf(ApiError);
+  });
+});
+
+describe('HttpTransport extraHeaders', () => {
+  it('merges extraHeaders into request() headers', async () => {
+    let captured: any;
+    vi.stubGlobal('fetch', vi.fn(async (_url: string, init: any) => { captured = init.headers; return new Response('{}', { status: 200 }); }));
+    const t = new HttpTransport('key', registry, { 'X-Hub-Auth-Type': 'clawkey' });
+    await t.request('GET', '/x');
+    expect(captured['X-Hub-Auth-Type']).toBe('clawkey');
+    expect(captured['Authorization']).toBe('Bearer key');
+  });
+  it('merges extraHeaders into getBytes() headers', async () => {
+    let captured: any;
+    vi.stubGlobal('fetch', vi.fn(async (_url: string, init: any) => { captured = init.headers; return new Response(new Uint8Array([1]), { status: 200 }); }));
+    const t = new HttpTransport('key', registry, { 'X-Hub-Auth-Type': 'clawkey' });
+    await t.getBytes('/x');
+    expect(captured['X-Hub-Auth-Type']).toBe('clawkey');
+  });
+});

package/src/lib/http-transport.ts

@@ -0,0 +1,113 @@
+// src/lib/http-transport.ts
+import type { ServerRegistry } from './server-registry.js';
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: string,
+    public readonly method: string,
+    public readonly path: string,
+  ) {
+    super(`API error ${status}: ${body}`);
+    this.name = 'ApiError';
+  }
+}
+
+function parseJsonBody(body: string): any | null {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
+export function formatApiError(err: ApiError): string {
+  if (err.status === 429) {
+    const data = parseJsonBody(err.body);
+    const error = data?.error ?? {};
+    const code = error?.code ?? data?.code ?? 'RATE_LIMITED';
+    const retryAfter = error?.retry_after ?? error?.['retry after'] ?? data?.retry_after ?? data?.['retry after'];
+    const hint = error?.hint ?? data?.hint;
+    const message = error?.message ?? data?.message ?? 'Too many requests.';
+    const retryText = retryAfter !== undefined ? ` Retry after ${retryAfter}s.` : '';
+    const hintText = hint ? ` Hint: ${hint}.` : '';
+    return `Rate limited (${code}). ${message}.${retryText}${hintText}`;
+  }
+  return `Request failed (${err.status}): ${err.body}`;
+}
+
+export class HttpTransport {
+  private apiKey: string;
+  private registry: ServerRegistry;
+  private extraHeaders: Record<string, string>;
+
+  constructor(apiKey: string, registry: ServerRegistry, extraHeaders: Record<string, string> = {}) {
+    this.apiKey = apiKey;
+    this.registry = registry;
+    this.extraHeaders = extraHeaders;
+  }
+
+  /**
+   * Generic HTTP request. Supports JSON body and FormData.
+   * Adds Authorization header when apiKey is non-empty.
+   */
+  async request<T = any>(method: string, path: string, body?: any): Promise<T> {
+    const url = this.registry.baseUrlFor(path) + path;
+    const headers: Record<string, string> = {};
+
+    // Only add auth header if apiKey is present (register endpoint has no auth)
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    for (const [k, v] of Object.entries(this.extraHeaders)) headers[k] = v;
+
+    let fetchBody: BodyInit | undefined;
+    if (body !== undefined) {
+      if (body instanceof FormData) {
+        fetchBody = body;
+        // Let fetch set Content-Type with boundary for FormData
+      } else {
+        headers['Content-Type'] = 'application/json; charset=utf-8';
+        fetchBody = JSON.stringify(body);
+      }
+    }
+
+    const res = await fetch(url, { method, headers, body: fetchBody, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) {
+      throw new ApiError(res.status, await res.text(), method, path);
+    }
+    return res.json() as Promise<T>;
+  }
+
+  /** GET with one fast retry for transient network failures. */
+  async get<T = any>(path: string): Promise<T> {
+    try {
+      return await this.request<T>('GET', path);
+    } catch (err) {
+      // Only retry network errors, not HTTP errors
+      if (err instanceof ApiError) throw err;
+      await new Promise(r => setTimeout(r, 500));
+      return this.request<T>('GET', path);
+    }
+  }
+
+  async post<T = any>(path: string, body?: any): Promise<T> {
+    return this.request<T>('POST', path, body);
+  }
+
+  /** GET raw bytes (binary artifacts). Throws ApiError on non-ok. */
+  async getBytes(path: string): Promise<Buffer> {
+    const url = this.registry.baseUrlFor(path) + path;
+    const headers: Record<string, string> = {};
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+    for (const [k, v] of Object.entries(this.extraHeaders)) headers[k] = v;
+    const res = await fetch(url, { method: 'GET', headers, signal: AbortSignal.timeout(30_000) });
+    if (!res.ok) {
+      throw new ApiError(res.status, await res.text(), 'GET', path);
+    }
+    return Buffer.from(await res.arrayBuffer());
+  }
+}

package/src/lib/hub-client.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { HubClient, parseResourceRef } from './hub-client.js';
+
+function fakeTransport() {
+  const calls: any[] = [];
+  const transport: any = {
+    calls,
+    async get(path: string) {
+      calls.push(['GET', path]);
+      if (path.includes('/resources/')) return { data: { id: 'abc', type: 'strategy', title: 'T' } };
+      return { data: { items: [], total: 0, pagination: { mode: 'page', page: 1, limit: 20, hasMore: false } } };
+    },
+    async getBytes(path: string) { calls.push(['GETBYTES', path]); return Buffer.from('raw'); },
+  };
+  return transport;
+}
+
+describe('parseResourceRef', () => {
+  it('splits type/id', () => {
+    expect(parseResourceRef('strategy/ab12cd')).toEqual({ type: 'strategy', id: 'ab12cd' });
+    expect(parseResourceRef('skill/xyz')).toEqual({ type: 'skill', id: 'xyz' });
+  });
+  it('rejects bad type', () => {
+    expect(() => parseResourceRef('plugin/abc')).toThrow(/invalid resource ref/);
+  });
+  it('rejects missing id', () => {
+    expect(() => parseResourceRef('strategy/')).toThrow(/invalid resource ref/);
+  });
+});
+
+describe('HubClient', () => {
+  it('list builds query and unwraps data', async () => {
+    const t = fakeTransport();
+    const res = await new HubClient(t).list({ type: 'skill', sort: 'downloads', q: '抢刀', limit: 10 });
+    expect(t.calls[0][1]).toBe('/api/client/v1/resources?type=skill&q=%E6%8A%A2%E5%88%80&sort=downloads&limit=10');
+    expect(res.total).toBe(0);
+    expect(res.items).toEqual([]);
+  });
+  it('list with no opts hits bare endpoint', async () => {
+    const t = fakeTransport();
+    await new HubClient(t).list();
+    expect(t.calls[0][1]).toBe('/api/client/v1/resources');
+  });
+  it('getResource builds typed path and unwraps data', async () => {
+    const t = fakeTransport();
+    const d = await new HubClient(t).getResource('strategy', 'ab12');
+    expect(t.calls[0]).toEqual(['GET', '/api/client/v1/resources/strategy/ab12']);
+    expect(d.id).toBe('abc');
+  });
+  it('downloadArtifact hits the /download endpoint (encoding id)', async () => {
+    const t = fakeTransport();
+    const buf = await new HubClient(t).downloadArtifact('skill', 'xy z');
+    expect(t.calls[0]).toEqual(['GETBYTES', '/api/client/v1/resources/skill/xy%20z/download']);
+    expect(Buffer.isBuffer(buf)).toBe(true);
+  });
+});

package/src/lib/hub-client.ts

@@ -0,0 +1,88 @@
+// src/lib/hub-client.ts
+import { AuthStore } from './auth.js';
+import { ServerRegistry } from './server-registry.js';
+import { HttpTransport } from './http-transport.js';
+
+export type ResourceType = 'skill' | 'strategy';
+
+export interface ResourceStats { downloadCount: number; starCount: number; commentCount: number; }
+
+export interface ResourceSummary {
+  id: string;
+  type: ResourceType;
+  title: string;
+  description: string;
+  creator: string;
+  creatorType: string;
+  creatorDisplayName: string;
+  creatorAvatarUrl: string | null;
+  fileName: string;
+  stats: ResourceStats;
+  downloadUrl: string;
+  likedByMe: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ResourceDetail extends ResourceSummary {
+  artifact: { fileName: string; downloadUrl: string };
+}
+
+export interface Pagination { mode: 'page' | 'none'; page?: number; limit?: number; hasMore: boolean; }
+export interface ResourceListResult { items: ResourceSummary[]; total: number; pagination: Pagination; }
+
+export interface ListOptions {
+  type?: ResourceType;
+  q?: string;
+  sort?: 'latest' | 'downloads' | 'stars';
+  pagination?: 'page' | 'none';
+  page?: number;
+  limit?: number;
+}
+
+const BASE = '/api/client/v1';
+const DEFAULT_HUB_URL = 'https://myclaw.163.com/hub';
+
+/** Parse a `<type>/<id>` resource ref (type ∈ skill|strategy). */
+export function parseResourceRef(ref: string): { type: ResourceType; id: string } {
+  const m = ref.match(/^(skill|strategy)\/([^/\s]+)$/);
+  if (!m) throw new Error(`invalid resource ref '${ref}' (expected <skill|strategy>/<id>)`);
+  return { type: m[1] as ResourceType, id: m[2] };
+}
+
+interface Envelope<T> { data: T; }
+
+export class HubClient {
+  constructor(private readonly http: HttpTransport) {}
+
+  static fromAuth(opts?: { authStore?: AuthStore }): HubClient {
+    const store = opts?.authStore ?? new AuthStore();
+    const profile = store.getActive();
+    const apiKey = profile?.apiKey ?? '';
+    const hubUrl = process.env.CLAWCLAW_HUB_URL || DEFAULT_HUB_URL;
+    const registry = new ServerRegistry({ lobbyUrl: hubUrl });
+    return new HubClient(new HttpTransport(apiKey, registry, { 'X-Hub-Auth-Type': 'clawkey' }));
+  }
+
+  async list(opts: ListOptions = {}): Promise<ResourceListResult> {
+    const qs = new URLSearchParams();
+    if (opts.type) qs.set('type', opts.type);
+    if (opts.q) qs.set('q', opts.q);
+    if (opts.sort) qs.set('sort', opts.sort);
+    if (opts.pagination) qs.set('pagination', opts.pagination);
+    if (opts.page !== undefined) qs.set('page', String(opts.page));
+    if (opts.limit !== undefined) qs.set('limit', String(opts.limit));
+    const suffix = qs.toString() ? `?${qs.toString()}` : '';
+    const res = await this.http.get<Envelope<ResourceListResult>>(`${BASE}/resources${suffix}`);
+    return res.data;
+  }
+
+  async getResource(type: ResourceType, id: string): Promise<ResourceDetail> {
+    const res = await this.http.get<Envelope<ResourceDetail>>(`${BASE}/resources/${type}/${encodeURIComponent(id)}`);
+    return res.data;
+  }
+
+  async downloadArtifact(type: ResourceType, id: string): Promise<Buffer> {
+    return this.http.getBytes(`${BASE}/resources/${type}/${encodeURIComponent(id)}/download`);
+  }
+}