me2lon 0.0.0-stage → 0.1.0

package/src/client.ts

@@ -0,0 +1,413 @@
+import { Me2lonAgentApi, mutationAttemptId } from "./api.js";
+import { Me2lonClientError } from "./errors.js";
+import {
+  assertNoForbiddenOutput,
+  projectCapabilities,
+  projectJob,
+  projectPolicy,
+  projectPolicyProposal,
+  projectPolicyUnits,
+  repositoryFromList,
+  requireResourceId,
+} from "./safe-output.js";
+import {
+  LOCAL_SOURCE_LIMITS,
+  SOURCE_SCHEMA_VERSION,
+  type AgentRuntimeConfig,
+  type JsonValue,
+  type SafeToolResult,
+  type SourceLimits,
+} from "./types.js";
+import { buildWorkspaceSource, buildWorkspaceSnapshot } from "./workspace-source.js";
+import { updateProjectState } from "./config.js";
+
+const MAX_RETURNED_DIAGNOSTICS = 2_000;
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+    ? value
+    : undefined;
+}
+
+function nonnegativeInteger(value: unknown): number | undefined {
+  return typeof value === "number" &&
+    Number.isSafeInteger(value) &&
+    value >= 0
+    ? value
+    : undefined;
+}
+
+function jobRecord(raw: Record<string, unknown>): Record<string, unknown> {
+  return object(raw.job) ??
+    object(raw.checkJob) ??
+    object(raw.translationJob) ??
+    object(raw.verificationJob) ??
+    object(raw.data) ??
+    raw;
+}
+
+function sourceLimits(raw: Record<string, unknown>): SourceLimits {
+  const capabilities = object(raw.capabilities) ?? raw;
+  const limits = object(capabilities.limits);
+  const source = object(limits?.source) ?? limits;
+  return {
+    maxChanges: Math.min(
+      LOCAL_SOURCE_LIMITS.maxChanges,
+      positiveInteger(source?.maxChanges) ?? LOCAL_SOURCE_LIMITS.maxChanges,
+    ),
+    maxFileBytes: Math.min(
+      LOCAL_SOURCE_LIMITS.maxFileBytes,
+      positiveInteger(source?.maxFileBytes) ?? LOCAL_SOURCE_LIMITS.maxFileBytes,
+    ),
+    maxTotalBytes: Math.min(
+      LOCAL_SOURCE_LIMITS.maxTotalBytes,
+      positiveInteger(source?.maxTotalBytes) ??
+        LOCAL_SOURCE_LIMITS.maxTotalBytes,
+    ),
+  };
+}
+
+function checked(result: SafeToolResult): SafeToolResult {
+  assertNoForbiddenOutput(result);
+  return result;
+}
+
+function validateBoundRepository(
+  response: Record<string, unknown>,
+  repositoryId: string,
+): void {
+  const candidates: Array<string | number> = [];
+  const visit = (value: unknown, depth: number): void => {
+    if (depth > 4 || !value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      for (const item of value.slice(0, 100)) visit(item, depth + 1);
+      return;
+    }
+    for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+      if (
+        key === "repositoryId" &&
+        (typeof nested === "string" || typeof nested === "number")
+      ) {
+        candidates.push(nested);
+      } else if (/^(?:data|job|workspace|revision|result)$/u.test(key)) {
+        visit(nested, depth + 1);
+      }
+    }
+  };
+  visit(response, 0);
+  if (candidates.some((value) => String(value) !== repositoryId)) {
+    throw new Me2lonClientError(
+      "ME2LON_REPOSITORY_MISMATCH",
+      "The API response belongs to a repository other than the MCP-bound repository.",
+    );
+  }
+}
+
+export type PolicyProposalInput = Readonly<{
+  policyUnitId: string;
+  expectedPolicySetDigest: string;
+  policy: JsonValue;
+  rationale?: string;
+}>;
+
+export class Me2lonAgentClient {
+  readonly #config: AgentRuntimeConfig;
+  readonly #api: Me2lonAgentApi;
+  #repositoryPromise?: Promise<Record<string, unknown>>;
+  #workspaceIdPromise?: Promise<string>;
+  readonly #newAttemptId: () => string;
+
+  constructor(
+    config: AgentRuntimeConfig,
+    api?: Me2lonAgentApi,
+    newAttemptId: () => string = mutationAttemptId,
+  ) {
+    this.#config = config;
+    this.#newAttemptId = newAttemptId;
+    this.#api =
+      api ??
+      new Me2lonAgentApi(
+        config.baseUrl,
+        config.token,
+        config.workspace.repositoryId,
+      );
+  }
+
+  async #repository(): Promise<Record<string, unknown>> {
+    this.#repositoryPromise ??= (async () => {
+      const raw = await this.#api.repositories();
+      const repository = repositoryFromList(
+        raw,
+        this.#config.workspace.repositoryId,
+      );
+      if (!repository) {
+        throw new Me2lonClientError(
+          "ME2LON_REPOSITORY_UNAUTHORIZED",
+          "The agent credential does not authorize the MCP-bound repository.",
+        );
+      }
+      return repository;
+    })();
+    return await this.#repositoryPromise;
+  }
+
+  async #workspaceId(): Promise<string> {
+    await this.#repository();
+    if (this.#config.workspaceId) return this.#config.workspaceId;
+    this.#workspaceIdPromise ??= (async () => {
+      const raw = await this.#api.createWorkspace(
+        this.#config.workspace.repositoryId,
+        this.#newAttemptId(),
+      );
+      validateBoundRepository(raw, this.#config.workspace.repositoryId);
+      const id = requireResourceId(raw, ["workspace"], ["workspaceId", "id"]);
+      await updateProjectState(this.#config, { workspaceId: id });
+      return id;
+    })();
+    return await this.#workspaceIdPromise;
+  }
+
+  async capabilities(): Promise<SafeToolResult> {
+    const [rawCapabilities, rawRepositories] = await Promise.all([
+      this.#api.capabilities(),
+      this.#api.repositories(),
+    ]);
+    const repository = repositoryFromList(
+      rawRepositories,
+      this.#config.workspace.repositoryId,
+    );
+    return checked(projectCapabilities(rawCapabilities, repository));
+  }
+
+  async analyzeWorkspace(projectRoot?: string, workspaceRevisionId?: string): Promise<SafeToolResult> {
+    if (workspaceRevisionId !== undefined) {
+      await this.#repository();
+      const raw = await this.#api.createAnalysisJob(workspaceRevisionId, projectRoot);
+      validateBoundRepository(raw, this.#config.workspace.repositoryId);
+      requireResourceId(raw, ['job'], ['id', 'jobId']);
+      return checked({ job: projectJob(raw) });
+    }
+    return this.captureWorkspace(true, projectRoot);
+  }
+
+  async checkWorkspace(): Promise<SafeToolResult> { return this.captureWorkspace(false); }
+
+  private async captureWorkspace(analyze: boolean, projectRoot?: string): Promise<SafeToolResult> {
+    const attemptId = this.#newAttemptId();
+    const [workspaceId, capabilities] = await Promise.all([
+      this.#workspaceId(),
+      this.#api.capabilities(),
+    ]);
+    if (this.#config.sourceFormat === "snapshot") {
+      const source = await buildWorkspaceSnapshot(this.#config.workspace, sourceLimits(capabilities));
+      const revision = await this.#api.createSnapshot(workspaceId, source, this.#config.previousRevisionId, attemptId);
+      validateBoundRepository(revision, this.#config.workspace.repositoryId);
+      const revisionId = requireResourceId(revision, ["revision"], ["id", "revisionId"]);
+      await updateProjectState(this.#config, { previousRevisionId: revisionId });
+      const job = await (analyze ? this.#api.createAnalysisJob(revisionId, projectRoot, attemptId) : this.#api.createCheckJob(revisionId, attemptId));
+      validateBoundRepository(job, this.#config.workspace.repositoryId);
+      requireResourceId(job, ["job", "checkJob"], ["jobId", "id"]);
+      return checked({ job: projectJob(job), upload: {
+        sourceSchemaVersion: source.schemaVersion, baseCommitSha: source.baseCommitSha,
+        branchLabel: source.branchLabel, digest: source.digest, fileCount: source.files.length,
+        totalReplacementBytes: source.totalReplacementBytes, workspaceRevisionId: revisionId,
+      } });
+    }
+    const source = await buildWorkspaceSource(
+      this.#config.workspace,
+      sourceLimits(capabilities),
+    );
+    const revision = await this.#api.createRevision(
+      workspaceId,
+      source,
+      attemptId,
+    );
+    validateBoundRepository(revision, this.#config.workspace.repositoryId);
+    const workspaceRevisionId = requireResourceId(
+      revision,
+      ["revision", "workspaceRevision"],
+      ["workspaceRevisionId", "revisionId", "id"],
+    );
+    const job = await (analyze ? this.#api.createAnalysisJob(workspaceRevisionId, projectRoot, attemptId) : this.#api.createCheckJob(workspaceRevisionId, attemptId));
+    validateBoundRepository(job, this.#config.workspace.repositoryId);
+    requireResourceId(job, ["job", "checkJob"], ["jobId", "id"]);
+    return checked({
+      job: projectJob(job),
+      upload: {
+        sourceSchemaVersion: SOURCE_SCHEMA_VERSION,
+        baseCommitSha: source.baseCommitSha,
+        digest: source.digest,
+        replacementCount: source.replacementCount,
+        deletionCount: source.deletionCount,
+        totalReplacementBytes: source.totalReplacementBytes,
+      },
+    });
+  }
+
+  async getJob(jobId: string): Promise<SafeToolResult> {
+    await this.#repository();
+    const raw = await this.#api.job(jobId);
+    validateBoundRepository(raw, this.#config.workspace.repositoryId);
+    const job = jobRecord(raw);
+    const kind = typeof job.kind === "string" ? job.kind.toLowerCase() : "";
+    const status =
+      typeof job.status === "string" ? job.status.toLowerCase() : "";
+    const diagnostics =
+      (kind === "analysis" || (kind === "check" && ["succeeded", "completed"].includes(status)))
+        ? await this.#checkDiagnostics(jobId)
+        : undefined;
+    return checked(projectJob(raw, diagnostics));
+  }
+
+  async #checkDiagnostics(jobId: string): Promise<Record<string, unknown>> {
+    const items: unknown[] = [];
+    let cursor = 0;
+    let total: number | undefined;
+    let nextCursor: number | null = null;
+    let pages = 0;
+
+    while (items.length < MAX_RETURNED_DIAGNOSTICS && pages < 4) {
+      pages += 1;
+      const page = await this.#api.jobDiagnostics(
+        jobId,
+        cursor,
+        Math.min(500, MAX_RETURNED_DIAGNOSTICS - items.length),
+      );
+      const body = object(page.data) ?? page;
+      const pageItems = Array.isArray(body.items) ? body.items : [];
+      items.push(...pageItems.slice(0, MAX_RETURNED_DIAGNOSTICS - items.length));
+      total = nonnegativeInteger(body.total) ?? total;
+      const candidate =
+        body.nextCursor === null ? null : nonnegativeInteger(body.nextCursor);
+      if (candidate === null || candidate === undefined || candidate <= cursor) {
+        nextCursor = null;
+        break;
+      }
+      nextCursor = candidate;
+      cursor = candidate;
+    }
+
+    if (pages === 4 && nextCursor !== null) {
+      nextCursor = cursor;
+    }
+
+    return {
+      items,
+      total: total ?? items.length,
+      nextCursor,
+      truncated:
+        nextCursor !== null ||
+        (total !== undefined && total > items.length),
+    };
+  }
+
+  async translate(checkJobId: string, projectId: string): Promise<SafeToolResult> {
+    await this.#repository();
+    const raw = await this.#api.createTranslationJob(
+      checkJobId,
+      projectId,
+      this.#newAttemptId(),
+    );
+    validateBoundRepository(raw, this.#config.workspace.repositoryId);
+    requireResourceId(raw, ["job", "translationJob"], ["jobId", "id"]);
+    return checked(projectJob(raw));
+  }
+
+  async verify(
+    translationJobId: string,
+    expectedPolicySetDigest: string,
+  ): Promise<SafeToolResult> {
+    await this.#repository();
+    const raw = await this.#api.createVerificationJob(
+      translationJobId,
+      expectedPolicySetDigest,
+      this.#newAttemptId(),
+    );
+    validateBoundRepository(raw, this.#config.workspace.repositoryId);
+    requireResourceId(raw, ["job", "verificationJob"], ["jobId", "id"]);
+    return checked(projectJob(raw));
+  }
+
+  async getPolicy(policyUnitId?: string): Promise<SafeToolResult> {
+    await this.#repository();
+    if (!policyUnitId) {
+      return checked(
+        projectPolicyUnits(
+          await this.#api.policyUnits(this.#config.workspace.repositoryId),
+        ),
+      );
+    }
+    return checked(projectPolicy(await this.#api.policyUnit(policyUnitId)));
+  }
+
+  async proposePolicy(input: PolicyProposalInput): Promise<SafeToolResult> {
+    await this.#repository();
+    const attemptId = this.#newAttemptId();
+    const draft = await this.#api.createPolicyDraft(
+      input.policyUnitId,
+      input.expectedPolicySetDigest,
+      attemptId,
+    );
+    const draftId = requireResourceId(draft, ["draft"], ["draftId", "id"]);
+    const revision = await this.#api.createPolicyRevision(
+      draftId,
+      input.expectedPolicySetDigest,
+      input.policy,
+      input.rationale,
+      attemptId,
+    );
+    const revisionId = requireResourceId(
+      revision,
+      ["revision"],
+      ["revisionId", "id"],
+    );
+    const validation = await this.#api.validatePolicyRevision(
+      revisionId,
+      attemptId,
+    );
+    const validationInput = object(validation.validation) ?? validation;
+    const diff = await this.#api.policyRevisionDiff(revisionId);
+    const approvalEligible =
+      validationInput.status === "valid_complete" &&
+      validationInput.approvalEligible === true;
+    if (!approvalEligible) {
+      return checked(
+        projectPolicyProposal({
+          draft,
+          revision,
+          validation,
+          diff,
+          submitted: false,
+        }),
+      );
+    }
+    const submission = await this.#api.submitPolicyRevision(
+      revisionId,
+      input.expectedPolicySetDigest,
+      attemptId,
+    );
+    return checked(
+      projectPolicyProposal({
+        draft,
+        revision,
+        validation,
+        diff,
+        submission,
+        submitted: true,
+      }),
+    );
+  }
+
+  async cancelJob(jobId: string): Promise<SafeToolResult> {
+    await this.#repository();
+    const raw = await this.#api.cancelJob(jobId);
+    validateBoundRepository(raw, this.#config.workspace.repositoryId);
+    return checked(projectJob(raw));
+  }
+}

package/src/config.ts

@@ -0,0 +1,252 @@
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+
+import { Me2lonClientError } from "./errors.js";
+import type {
+  AgentRuntimeConfig,
+  ConfigFileShape,
+} from "./types.js";
+import { bindWorkspace, discoverWorkspace } from "./workspace-source.js";
+
+export function projectConfigPath(root: string, environment: NodeJS.ProcessEnv = process.env): string {
+  return join(environment.XDG_CONFIG_HOME || join(homedir(), ".config"), "me2lon", "projects",
+    `${createHash("sha256").update(root).digest("hex")}.json`);
+}
+
+export async function writeProjectConfig(path: string, value: ConfigFileShape): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    await rename(temporary, path);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+export async function updateProjectState(config: AgentRuntimeConfig, state: { workspaceId?: string; previousRevisionId?: string }): Promise<void> {
+  if (!config.configPath || config.sourceFormat !== "snapshot") return;
+  const current = await readConfigFile(config.configPath);
+  if (current.repositoryId !== config.workspace.repositoryId || current.workspaceRoot !== config.workspace.root ||
+    current.baseUrl !== config.baseUrl.origin || current.credentialId !== config.credentialId) {
+    throw new Me2lonClientError("ME2LON_CONFIG_CHANGED", "The project connection changed; restart the client.");
+  }
+  await writeProjectConfig(config.configPath, { ...current, ...state });
+  Object.assign(config, state);
+}
+
+export type RuntimeConfigOverrides = {
+  baseUrl?: string;
+  tokenFromStdin?: string;
+  workspaceRoot?: string;
+  repositoryId?: string;
+  baseCommitSha?: string;
+  configPath?: string;
+}
+
+function optionalNonEmptyString(
+  value: unknown,
+  field: string,
+): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_INVALID",
+      `Configuration field ${field} must be a non-empty string.`,
+    );
+  }
+  return value.trim();
+}
+
+export async function readConfigFile(
+  configPath: string | undefined,
+): Promise<ConfigFileShape> {
+  if (!configPath) {
+    return {};
+  }
+
+  const absolutePath = resolve(configPath);
+  let metadata;
+  try {
+    metadata = await stat(absolutePath);
+  } catch (error) {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_UNREADABLE",
+      `Cannot read the Me2lon configuration file at ${absolutePath}.`,
+      { cause: error },
+    );
+  }
+  if (!metadata.isFile()) {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_INVALID",
+      `The Me2lon configuration path is not a regular file: ${absolutePath}.`,
+    );
+  }
+  if (process.platform !== "win32" && (metadata.mode & 0o077) !== 0) {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_PERMISSIONS",
+      "The Me2lon configuration file contains credentials and must not be accessible by group or other users (use mode 0600).",
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(absolutePath, "utf8"));
+  } catch (error) {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_INVALID",
+      "The Me2lon configuration file must contain valid JSON.",
+      { cause: error },
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_INVALID",
+      "The Me2lon configuration file must contain a JSON object.",
+    );
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const result: ConfigFileShape = {};
+  const baseUrl = optionalNonEmptyString(record.baseUrl, "baseUrl");
+  const token = optionalNonEmptyString(record.token, "token");
+  const workspaceRoot = optionalNonEmptyString(
+    record.workspaceRoot,
+    "workspaceRoot",
+  );
+  const repositoryId = optionalNonEmptyString(
+    record.repositoryId,
+    "repositoryId",
+  );
+  const baseCommitSha = optionalNonEmptyString(
+    record.baseCommitSha,
+    "baseCommitSha",
+  );
+  if (baseUrl) result.baseUrl = baseUrl;
+  if (token) result.token = token;
+  if (workspaceRoot) result.workspaceRoot = workspaceRoot;
+  if (repositoryId) result.repositoryId = repositoryId;
+  if (baseCommitSha) result.baseCommitSha = baseCommitSha;
+  if (record.sourceFormat !== undefined) {
+    if (record.sourceFormat !== "snapshot") throw new Me2lonClientError("ME2LON_CONFIG_INVALID", "Unknown source format.");
+    result.sourceFormat = "snapshot";
+  }
+  for (const field of ["credentialId", "workspaceId", "previousRevisionId"] as const) {
+    const value = optionalNonEmptyString(record[field], field);
+    if (value !== undefined) result[field] = value;
+  }
+  return result;
+}
+
+export function parseBaseUrl(raw: string): URL {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch (error) {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_INVALID",
+      "The Me2lon API URL is invalid.",
+      { cause: error },
+    );
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_INVALID",
+      "The Me2lon API URL cannot contain credentials, a query, or a fragment.",
+    );
+  }
+  if (url.pathname !== "/") {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_INVALID",
+      "The Me2lon API URL must be an origin without a path.",
+    );
+  }
+  const loopback = new Set(["localhost", "127.0.0.1", "[::1]"]);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback.has(url.hostname))) {
+    throw new Me2lonClientError(
+      "ME2LON_INSECURE_URL",
+      "The Me2lon API URL must use HTTPS (HTTP is accepted only for loopback development).",
+    );
+  }
+  return url;
+}
+
+function required(value: string | undefined, label: string): string {
+  if (!value) {
+    throw new Me2lonClientError(
+      "ME2LON_CONFIG_MISSING",
+      `Missing ${label}.`,
+    );
+  }
+  return value;
+}
+
+export async function resolveRuntimeConfig(
+  overrides: RuntimeConfigOverrides,
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<AgentRuntimeConfig> {
+  let configPath = overrides.configPath ?? environment.ME2LON_AGENT_CONFIG;
+  if (!configPath) {
+    const workspace = await discoverWorkspace(overrides.workspaceRoot ?? environment.ME2LON_WORKSPACE_ROOT ?? process.cwd());
+    const candidate = projectConfigPath(workspace.root, environment);
+    try { await stat(candidate); configPath = candidate; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+  const file = await readConfigFile(configPath);
+  const token =
+    overrides.tokenFromStdin?.trim() ||
+    environment.ME2LON_AGENT_TOKEN?.trim() ||
+    file.token?.trim();
+  if (!token) {
+    throw new Me2lonClientError(
+      "ME2LON_TOKEN_MISSING",
+      "Run me2lon setup to connect this project. Existing tokens can also use ME2LON_AGENT_TOKEN, a protected config file, or --token-stdin.",
+    );
+  }
+  if (token.length > 8_192 || /[\r\n]/u.test(token)) {
+    throw new Me2lonClientError(
+      "ME2LON_TOKEN_INVALID",
+      "The Me2lon agent token has an invalid shape.",
+    );
+  }
+
+  const baseUrl = parseBaseUrl(
+    required(
+      overrides.baseUrl ?? environment.ME2LON_AGENT_URL ?? file.baseUrl,
+      "Me2lon API URL (--base-url or ME2LON_AGENT_URL)",
+    ),
+  );
+  const root =
+    overrides.workspaceRoot ??
+    environment.ME2LON_WORKSPACE_ROOT ??
+    file.workspaceRoot ??
+    process.cwd();
+  const repositoryId = required(
+    overrides.repositoryId ??
+      environment.ME2LON_REPOSITORY_ID ??
+      file.repositoryId,
+    "repository id (--repository-id or ME2LON_REPOSITORY_ID)",
+  );
+  if (file.sourceFormat === "snapshot" && (overrides.baseCommitSha || environment.ME2LON_BASE_COMMIT)) {
+    throw new Me2lonClientError("ME2LON_CONFIG_INVALID", "Full snapshots capture the current HEAD; remove the base-commit override.");
+  }
+  const baseCommitSha = file.sourceFormat === "snapshot" ? (await discoverWorkspace(root)).head : required(
+    overrides.baseCommitSha ??
+      environment.ME2LON_BASE_COMMIT ??
+      file.baseCommitSha,
+    "exact base commit (--base-commit or ME2LON_BASE_COMMIT)",
+  );
+
+  return {
+    baseUrl,
+    token,
+    workspace: await bindWorkspace(root, repositoryId, baseCommitSha),
+    ...(configPath ? { configPath: resolve(configPath) } : {}),
+    ...(file.sourceFormat ? { sourceFormat: file.sourceFormat } : {}),
+    ...(file.credentialId ? { credentialId: file.credentialId } : {}),
+    ...(file.workspaceId ? { workspaceId: file.workspaceId } : {}),
+    ...(file.previousRevisionId ? { previousRevisionId: file.previousRevisionId } : {}),
+  };
+}

package/src/errors.ts

@@ -0,0 +1,40 @@
+export class Me2lonClientError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "Me2lonClientError";
+    this.code = code;
+  }
+}
+
+export class Me2lonApiError extends Me2lonClientError {
+  readonly status: number;
+  readonly requestId?: string;
+
+  constructor(status: number, requestId?: string) {
+    const requestSuffix = requestId ? `; request ${requestId}` : "";
+    super(
+      status === 401 ? "ME2LON_AUTHENTICATION_REQUIRED" : "ME2LON_API_ERROR",
+      status === 401 ? "Me2lon authentication expired or was revoked. Run me2lon setup, then retry." : `Me2lon API request failed with HTTP ${status}${requestSuffix}.`,
+    );
+    this.name = "Me2lonApiError";
+    this.status = status;
+    if (requestId) {
+      this.requestId = requestId;
+    }
+  }
+}
+
+export function publicError(error: unknown): {
+  code: string;
+  message: string;
+} {
+  if (error instanceof Me2lonClientError) {
+    return { code: error.code, message: error.message };
+  }
+  return {
+    code: "ME2LON_CLIENT_FAILURE",
+    message: "The Me2lon client could not complete the request.",
+  };
+}