draftgo-cli 1.0.4

package/src/worktree/backend.js

@@ -0,0 +1,438 @@
+'use strict';
+
+const fs = require('fs');
+const { Readable } = require('stream');
+const { DraftGoMcpClient } = require('../mcp/client');
+const { BackendHttpError, WorktreeError } = require('./errors');
+const { canonicalResourceType, mediaType, normalizeExtension } = require('./types');
+const { normalizeSha256 } = require('./streams');
+
+const METADATA_TOOL = 'draftgo_resource_get_metadata';
+const MAX_ERROR_BYTES = 64 * 1024;
+const MAX_JSON_BYTES = 1024 * 1024;
+const MAX_CHECKOUT_JSON_BYTES = 64 * 1024 * 1024;
+const FINAL_OPERATIONS = Object.freeze({
+  pages: Object.freeze({ checkout: 'listPageCheckout', commit: 'updatePageCommit', contentType: 'text/html; charset=utf-8' }),
+  navigations: Object.freeze({ checkout: 'listNavigationCheckout', commit: 'updateNavigationCommit', contentType: 'text/html; charset=utf-8' }),
+  docs: Object.freeze({ checkout: 'listContentArticleCheckout', commit: 'updateContentArticleCommit', contentType: 'text/html; charset=utf-8', jsonCommit: true }),
+});
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function toolNameMatches(name, expected) {
+  return name === expected
+    || name.endsWith(`.${expected}`)
+    || name.endsWith(`/${expected}`)
+    || name.endsWith(`:${expected}`);
+}
+
+function parseJsonText(text, label) {
+  try { return JSON.parse(text); } catch {
+    throw new WorktreeError('INVALID_BACKEND_RESPONSE', `${label} did not return structured JSON.`);
+  }
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function isMcpPayload(value) {
+  return isObject(value) && (
+    hasOwn(value, 'jsonrpc')
+    || hasOwn(value, 'result')
+    || hasOwn(value, 'structuredContent')
+    || hasOwn(value, 'structured_content')
+    || hasOwn(value, 'content')
+    || hasOwn(value, 'isError')
+    || hasOwn(value, 'ok')
+  );
+}
+
+function toolError(envelope, fallbackCode, fallbackMessage) {
+  const error = isObject(envelope && envelope.error) ? envelope.error : {};
+  return new WorktreeError(
+    String(firstValue(error.code, fallbackCode)),
+    String(firstValue(error.message, fallbackMessage)),
+    isObject(error.details) ? error.details : {},
+  );
+}
+
+function unwrapToolResult(payload) {
+  if (!isObject(payload)) {
+    throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo MCP tool returned no structured result.');
+  }
+
+  let result = payload;
+  if (hasOwn(payload, 'jsonrpc') || hasOwn(payload, 'result')) {
+    if (isObject(payload.error)) {
+      throw toolError({ error: payload.error }, 'MCP_RPC_ERROR', 'DraftGo MCP request failed.');
+    }
+    if (!isObject(payload.result)) {
+      throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo MCP returned no tool result.');
+    }
+    result = payload.result;
+  }
+
+  if (!isObject(result)) {
+    throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo MCP returned an invalid tool result.');
+  }
+  if (hasOwn(result, 'isError') && typeof result.isError !== 'boolean') {
+    throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo MCP returned an invalid isError value.');
+  }
+
+  let envelope;
+  if (hasOwn(result, 'structuredContent')) {
+    if (!isObject(result.structuredContent)) {
+      throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo MCP returned invalid structuredContent.');
+    }
+    envelope = result.structuredContent;
+  } else if (hasOwn(result, 'structured_content')) {
+    if (!isObject(result.structured_content)) {
+      throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo MCP returned invalid structured_content.');
+    }
+    envelope = result.structured_content;
+  } else if (Array.isArray(result.content)) {
+    const textPart = result.content.find((part) => part && part.type === 'text' && typeof part.text === 'string');
+    if (textPart && Buffer.byteLength(textPart.text, 'utf8') <= MAX_JSON_BYTES) {
+      envelope = parseJsonText(textPart.text, 'DraftGo MCP tool');
+    }
+  } else if (hasOwn(result, 'ok')) {
+    envelope = result;
+  }
+
+  if (!isObject(envelope)) {
+    throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo MCP tool returned no structured JSON result.');
+  }
+  if (result.isError === true) {
+    throw toolError(envelope, 'MCP_TOOL_ERROR', 'DraftGo MCP tool reported an error.');
+  }
+  if (envelope.ok !== true) {
+    throw toolError(envelope, 'INVALID_BACKEND_RESPONSE', 'DraftGo MCP tool did not report success.');
+  }
+  return envelope.data;
+}
+
+function unwrapProtectedResult(data, label = 'DraftGo resource tool') {
+  if (!isObject(data) || !hasOwn(data, 'value') || typeof data.omitted !== 'boolean') {
+    throw new WorktreeError(
+      'INVALID_PROTECTED_RESULT',
+      `${label} returned an invalid protected result.`,
+    );
+  }
+  if (data.artifacts !== undefined && !Array.isArray(data.artifacts)) {
+    throw new WorktreeError(
+      'INVALID_PROTECTED_RESULT',
+      `${label} returned invalid artifact descriptors.`,
+    );
+  }
+  if (data.omitted || (Array.isArray(data.artifacts) && data.artifacts.length > 0)) {
+    throw new WorktreeError(
+      'PROTECTED_RESULT_OMITTED',
+      `${label} omitted fields required by the CLI.`,
+      { artifacts: data.artifacts || [] },
+    );
+  }
+  return data.value;
+}
+
+function firstObject(...values) {
+  return values.find(isObject) || {};
+}
+
+function firstValue(...values) {
+  return values.find((value) => value !== undefined && value !== null && value !== '');
+}
+
+function operationPath(config, template, resourceId) {
+  const encoded = encodeURIComponent(String(resourceId));
+  const relative = String(template || '').replace(/\{[^}]+\}/, encoded);
+  if (!relative.startsWith('/api/')) {
+    throw new WorktreeError('INVALID_WORKFLOW_PATH', 'DraftGo checkout workflow returned an invalid API path.');
+  }
+  return new URL(relative, `${config.server.replace(/\/+$/, '')}/`).toString();
+}
+
+async function finalMetadata(config, resourceType, resourceId, session, options = {}) {
+  // Loaded lazily to avoid the API command's dependency on this backend module.
+  const { registryRevision, describeOperation } = require('../commands/api');
+  const { TOOL_NAMES, callStructured } = require('../mcp/tools');
+  const type = canonicalResourceType(resourceType);
+  const spec = FINAL_OPERATIONS[type];
+  const revision = await registryRevision(session, spec.checkout);
+  const checkout = await describeOperation(options.projectDir || process.cwd(), config, session, spec.checkout, revision);
+  const commit = await describeOperation(options.projectDir || process.cwd(), config, session, spec.commit, revision);
+  const checkoutOperation = checkout && checkout.operation || {};
+  const commitOperation = commit && commit.operation || {};
+  const checkoutResult = await callStructured(session, TOOL_NAMES.apiCall, {
+    operation_id: spec.checkout,
+    registry_revision: revision,
+    path: { id: Number(resourceId) },
+  }, options);
+  const workflow = checkoutResult && checkoutResult.workflow || {};
+  if (workflow.required !== true || workflow.workflow !== 'checkout_commit') {
+    throw new WorktreeError('INVALID_WORKFLOW_DESCRIPTOR', 'DraftGo did not return a checkout/commit workflow descriptor.');
+  }
+  const checkoutURL = operationPath(config, checkoutOperation.path || workflow.path, resourceId);
+  const response = await (options.fetch || fetch)(checkoutURL, {
+    method: String(checkoutOperation.method || 'GET').toUpperCase(),
+    headers: authHeaders(config, { Accept: 'application/json' }),
+    signal: options.signal,
+    redirect: 'error',
+  });
+  if (!response.ok) throw await errorForResponse(response, config.token || config.sat);
+  const raw = await readBounded(response, MAX_CHECKOUT_JSON_BYTES, true);
+  const value = parseJsonText(raw, 'DraftGo checkout endpoint');
+  const version = firstValue(value.content_version, value.revision);
+  const content = typeof value.content === 'string' ? value.content : null;
+  const contentURL = firstValue(value.content_url, checkoutURL);
+  const contentType = type === 'docs' ? spec.contentType : spec.contentType;
+  const size = content == null ? null : Buffer.byteLength(content, 'utf8');
+  return normalizeMetadata(config, type, resourceId, {
+    resource_type: type,
+    resource_id: String(resourceId),
+    title: value.title || '', route: value.route || null, code: value.code || null, slug: value.slug || null,
+    content_type: contentType,
+    file_extension: '.html',
+    content_size: size,
+    content_hash: value.content_hash,
+    ...(type === 'docs' ? { base_revision: version } : { base_version: version }),
+    etag: value.content_hash,
+    download_url: contentURL,
+    commit_url: operationPath(config, commitOperation.path, resourceId),
+    commit_method: String(commitOperation.method || 'PUT').toUpperCase(),
+    inline_content: content,
+    json_commit: spec.jsonCommit === true,
+  });
+}
+
+function normalizeUrl(config, value, purpose) {
+  if (!value) return null;
+  let url;
+  try { url = new URL(String(value), `${config.server.replace(/\/+$/, '')}/`); } catch {
+    throw new WorktreeError('INVALID_BACKEND_URL', `DraftGo returned an invalid ${purpose} URL.`);
+  }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+    throw new WorktreeError('INVALID_BACKEND_URL', `DraftGo returned an unsafe ${purpose} URL.`);
+  }
+  const serverOrigin = new URL(config.server).origin;
+  const allowed = new Set([
+    serverOrigin,
+    ...((config.checkout && config.checkout.allowed_origins) || []).map((origin) => new URL(origin).origin),
+  ]);
+  if (!allowed.has(url.origin)) {
+    throw new WorktreeError(
+      'UNTRUSTED_BACKEND_ORIGIN',
+      `${purpose} URL origin is not allowlisted; refusing to send the API Key.`,
+      { origin: url.origin },
+    );
+  }
+  return url.toString();
+}
+
+function normalizeMetadata(config, resourceType, resourceId, payload) {
+  const data = isMcpPayload(payload)
+    ? unwrapProtectedResult(unwrapToolResult(payload), 'DraftGo metadata tool')
+    : payload;
+  if (!isObject(data)) {
+    throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo returned invalid checkout metadata.');
+  }
+  const checkout = isObject(data.checkout) ? data.checkout : {};
+  const checkoutConfig = firstObject(config.checkout);
+  const version = firstValue(data.base_version, data.version, data.revision, data.base_revision);
+  const hash = data.content_hash;
+  const contentType = data.content_type;
+  const backendExtension = data.file_extension;
+  const downloadRaw = firstValue(checkout.download, data.download_url);
+  const commitRaw = firstValue(checkout.commit, data.commit_url);
+
+  if (!contentType || !hash || version === undefined || !downloadRaw || !commitRaw) {
+    throw new WorktreeError(
+      'INCOMPLETE_CHECKOUT_METADATA',
+      'DraftGo checkout metadata must include content_type, SHA-256, base version/revision, download URL, and commit URL.',
+    );
+  }
+  const normalizedHash = normalizeSha256(hash);
+  if (!normalizedHash) throw new WorktreeError('INVALID_CONTENT_HASH', 'DraftGo returned an invalid content SHA-256.');
+
+  return {
+    resource_type: canonicalResourceType(firstValue(data.resource_type, resourceType)),
+    resource_id: String(firstValue(data.resource_id, resourceId)),
+    title: String(firstValue(data.title, '')),
+    route: firstValue(data.route, null),
+    code: firstValue(data.code, null),
+    slug: firstValue(data.slug, null),
+    content_type: String(contentType),
+    file_extension: normalizeExtension(contentType, backendExtension),
+    content_size: data.content_size == null ? null : Number(data.content_size),
+    content_hash: normalizedHash,
+    base_version: data.base_version !== undefined ? data.base_version : (data.version !== undefined ? data.version : null),
+    base_revision: data.base_revision !== undefined ? data.base_revision : (data.revision !== undefined ? data.revision : null),
+    etag: firstValue(data.etag, null),
+    updated_at: firstValue(data.updated_at, null),
+    updated_by: firstValue(data.updated_by, null),
+    download_url: normalizeUrl(config, downloadRaw, 'download'),
+    commit_url: commitRaw ? normalizeUrl(config, commitRaw, 'commit') : null,
+    commit_method: String(firstValue(data.commit_method, checkoutConfig.commit_method, 'PUT')).toUpperCase(),
+    raw: data,
+  };
+}
+
+async function resolveMetadata(config, resourceType, resourceId, options = {}) {
+  if (options.metadata) return normalizeMetadata(config, resourceType, resourceId, options.metadata);
+  const client = options.client || new DraftGoMcpClient(config);
+  if (!options.clientInitialized) await client.initialize(options);
+  let toolName = METADATA_TOOL;
+  if (typeof client.listAllTools === 'function') {
+    const tools = options.tools || await client.listAllTools(options);
+    const found = tools.find((tool) => tool && toolNameMatches(String(tool.name || ''), METADATA_TOOL));
+    if (!found) {
+      const { TOOL_NAMES, openToolSession } = require('../mcp/tools');
+      const session = await openToolSession(config, [
+        TOOL_NAMES.apiSearch, TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall,
+      ], { ...options, client });
+      return finalMetadata(config, resourceType, resourceId, session, options);
+    }
+    toolName = found.name;
+  } else if (Array.isArray(options.tools)) {
+    const found = options.tools.find((tool) => tool && toolNameMatches(String(tool.name || ''), METADATA_TOOL));
+    if (!found) {
+      const { TOOL_NAMES, openToolSession } = require('../mcp/tools');
+      const session = await openToolSession(config, [
+        TOOL_NAMES.apiSearch, TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall,
+      ], { ...options, client });
+      return finalMetadata(config, resourceType, resourceId, session, options);
+    }
+    toolName = found.name;
+  }
+  const result = await client.toolsCall(toolName, {
+    resource_type: canonicalResourceType(resourceType),
+    resource_id: String(resourceId),
+  }, options);
+  return normalizeMetadata(config, resourceType, resourceId, result);
+}
+
+function authHeaders(config, extra = {}) {
+  return { Authorization: `Bearer ${config.token || config.sat}`, ...extra };
+}
+
+async function readBounded(response, maximum = MAX_ERROR_BYTES, rejectOverflow = false) {
+  if (!response.body) return '';
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const chunk = Buffer.from(value);
+      if (size + chunk.length > maximum) {
+        if (rejectOverflow) throw new WorktreeError('RESPONSE_TOO_LARGE',
+          'DraftGo response exceeds the explicit ' + maximum + '-byte limit; local content was preserved.', { max_bytes: maximum });
+        chunks.push(chunk.subarray(0, maximum - size));
+        break;
+      }
+      chunks.push(chunk);
+      size += chunk.length;
+    }
+  } finally { await reader.cancel().catch(() => {}); }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function errorForResponse(response, token) {
+  const text = await readBounded(response);
+  let details = {};
+  try { details = text ? JSON.parse(text) : {}; } catch { details = { response: text }; }
+  const error = firstObject(details.error, details);
+  const code = firstValue(error.code, details.code, response.status === 409 || response.status === 412
+    ? 'RESOURCE_VERSION_CONFLICT' : 'BACKEND_HTTP_ERROR');
+  let message = String(firstValue(error.message, details.message, `DraftGo HTTP ${response.status}`));
+  if (token) message = message.split(String(token)).join('[REDACTED]');
+  return new BackendHttpError(response.status, code, message, isObject(error.details) ? error.details : details);
+}
+
+async function download(config, metadata, options = {}) {
+  const raw = metadata.raw && typeof metadata.raw === 'object' ? metadata.raw : {};
+  if (typeof raw.inline_content === 'string') {
+    return new Response(raw.inline_content, { headers: { 'content-type': metadata.content_type } });
+  }
+  const response = await (options.fetch || fetch)(metadata.download_url, {
+    method: 'GET',
+    headers: authHeaders(config, { Accept: '*/*' }),
+    signal: options.signal,
+    redirect: 'error',
+  });
+  if (!response.ok) throw await errorForResponse(response, config.token || config.sat);
+  return response;
+}
+
+async function commit(config, metadata, localPath, current, options = {}) {
+  if (!metadata.commit_url) {
+    throw new WorktreeError(
+      'COMMIT_URL_UNAVAILABLE',
+      'DraftGo metadata did not provide a commit URL.',
+    );
+  }
+  if (!['POST', 'PUT', 'PATCH'].includes(metadata.commit_method)) {
+    throw new WorktreeError('INVALID_COMMIT_METHOD', 'DraftGo returned an unsupported commit method.');
+  }
+  const headers = authHeaders(config, {
+    'Content-Type': metadata.content_type,
+    'Content-Length': String(current.size),
+    'X-Content-SHA256': current.hash,
+  });
+  if (metadata.etag) headers['If-Match'] = String(metadata.etag);
+  else if (metadata.base_version != null) headers['If-Match'] = String(metadata.base_version);
+  else if (metadata.base_revision != null) headers['If-Match'] = String(metadata.base_revision);
+  if (metadata.base_version != null) headers['DraftGo-Base-Version'] = String(metadata.base_version);
+  if (metadata.base_revision != null) headers['DraftGo-Base-Revision'] = String(metadata.base_revision);
+
+  let body;
+  let duplex;
+  if (metadata.raw && metadata.raw.json_commit === true) {
+    const content = fs.readFileSync(localPath, 'utf8');
+    body = JSON.stringify({
+      content,
+      ...(metadata.base_revision != null ? { base_revision: metadata.base_revision } : {}),
+      ...(metadata.base_revision == null && metadata.content_hash ? { base_hash: metadata.content_hash } : {}),
+    });
+    headers['Content-Type'] = 'application/json';
+    headers['Content-Length'] = String(Buffer.byteLength(body, 'utf8'));
+  } else {
+    body = fs.createReadStream(localPath);
+    duplex = 'half';
+  }
+  const response = await (options.fetch || fetch)(metadata.commit_url, {
+    method: metadata.commit_method,
+    headers,
+    body,
+    ...(duplex ? { duplex } : {}),
+    signal: options.signal,
+    redirect: 'error',
+  });
+  if (!response.ok) throw await errorForResponse(response, config.token || config.sat);
+  const text = await readBounded(response, MAX_JSON_BYTES, true);
+  if (!text.trim()) return {};
+  return parseJsonText(text, 'DraftGo commit endpoint');
+}
+
+function nodeReadable(response) {
+  if (!response.body) throw new WorktreeError('DOWNLOAD_INCOMPLETE', 'DraftGo response has no body.');
+  return typeof response.body.getReader === 'function' ? Readable.fromWeb(response.body) : response.body;
+}
+
+module.exports = {
+  METADATA_TOOL,
+  readBounded,
+  MAX_CHECKOUT_JSON_BYTES,
+  toolNameMatches,
+  unwrapToolResult,
+  unwrapProtectedResult,
+  normalizeMetadata,
+  resolveMetadata,
+  download,
+  commit,
+  nodeReadable,
+  errorForResponse,
+};

package/src/worktree/errors.js

@@ -0,0 +1,28 @@
+'use strict';
+
+class WorktreeError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'WorktreeError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+class BackendHttpError extends WorktreeError {
+  constructor(status, code, message, details = {}) {
+    super(code || 'BACKEND_HTTP_ERROR', message || `Backend request failed with HTTP ${status}.`, details);
+    this.name = 'BackendHttpError';
+    this.status = status;
+  }
+}
+
+function isVersionConflict(error) {
+  return Boolean(error) && (
+    error.code === 'RESOURCE_VERSION_CONFLICT'
+    || error.status === 409
+    || error.status === 412
+  );
+}
+
+module.exports = { WorktreeError, BackendHttpError, isVersionConflict };