draftgo-cli 1.0.5 → 1.0.7

package/src/commands/checkout.js

@@ -1,15 +1,62 @@
 'use strict';
 
 const log = require('../logger');
+const { loadProjectConfig } = require('../projectConfig');
+const { TOOL_NAMES, openToolSession } = require('../mcp/tools');
+const { canonicalResourceType } = require('../worktree/types');
 const { checkoutResources } = require('../worktree');
+const map = require('./map');
+
+const USAGE = 'Usage: draftgo checkout <pages|nav|docs|services> <id...>';
+
+async function resolveUniqueHit(projectDir, resourceType, flags) {
+  const canonical = canonicalResourceType(resourceType);
+  if (canonical === 'services') {
+    log.err('Checkout --route and --title are not supported for services.');
+    return null;
+  }
+  const config = loadProjectConfig(projectDir);
+  const resourceTypes = [map.normalizeMapResourceType(resourceType)];
+  const searching = flags.route != null || flags.title != null;
+  let remote;
+  try {
+    const session = await openToolSession(config, [searching ? TOOL_NAMES.resourceSearch : TOOL_NAMES.resourceList]);
+    remote = await map.listMapResources(session, resourceTypes, flags);
+  } catch (error) {
+    if (!error || error.code !== 'MCP_TOOL_UNAVAILABLE') throw error;
+    const session = await openToolSession(config, [TOOL_NAMES.apiSearch, TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall]);
+    remote = await map.listRegistryResources(projectDir, config, session, resourceTypes, flags);
+  }
+  const matches = (remote && remote.resources || []).filter((resource) => map.resourceMatches(resource, flags));
+  if (matches.length === 0) {
+    log.err(`No ${canonical} matched the given --route/--title.`);
+    return null;
+  }
+  if (matches.length !== 1) {
+    log.err(`Checkout --route/--title matched ${matches.length} ${canonical}; require exactly one.`);
+    return null;
+  }
+  return String(matches[0].resource_id);
+}
 
 async function checkout(projectDir, positional, flags = {}) {
   const [resourceType, ...ids] = positional;
-  if (!resourceType || !ids.length) {
-    log.err('Usage: draftgo checkout <pages|nav|docs> <id...>');
+  const selecting = flags.route != null || flags.title != null;
+  if (!resourceType || (!ids.length && !selecting)) {
+    log.err(USAGE);
     return 1;
   }
-  const results = await checkoutResources(projectDir, resourceType, ids, { force: Boolean(flags.force) });
+  let resourceIds = ids;
+  if (selecting) {
+    if (ids.length) {
+      log.err('Checkout --route/--title cannot be combined with resource ids.');
+      return 1;
+    }
+    const resourceId = await resolveUniqueHit(projectDir, resourceType, flags);
+    if (!resourceId) return 1;
+    resourceIds = [resourceId];
+  }
+  const results = await checkoutResources(projectDir, resourceType, resourceIds, { force: Boolean(flags.force) });
   if (flags.output === 'json') console.log(JSON.stringify(results, null, 2));
   else for (const entry of results) log.ok(`Checked out ${entry.resource_type} ${entry.resource_id} -> ${entry.local_path}`);
   return 0;

package/src/commands/commit.js

@@ -6,7 +6,7 @@ const { commitResources } = require('../worktree');
 async function commit(projectDir, positional, flags = {}) {
   const [resourceType, ...ids] = positional;
   if (!resourceType || !ids.length) {
-    log.err('Usage: draftgo commit <pages|nav|docs> <id...>');
+    log.err('Usage: draftgo commit <pages|nav|docs|services> <id...>');
     return 1;
   }
   const streamed = [];

package/src/commands/conflict.js

@@ -15,7 +15,7 @@ function printRecord(record) {
 async function conflict(projectDir, positional, flags = {}) {
   const [action, resourceType, resourceId] = positional;
   if (!['show', 'resolve'].includes(action) || !resourceType || !resourceId) {
-    log.err('Usage: draftgo conflict <show|resolve> <pages|nav|docs> <id>');
+    log.err('Usage: draftgo conflict <show|resolve> <pages|nav|docs|services> <id>');
     return 1;
   }
   const record = action === 'show'

package/src/commands/diff.js

@@ -8,7 +8,7 @@ const { absolutePath } = require('../worktree/manifest');
 function diff(projectDir, positional, flags = {}) {
   const [resourceType, resourceId] = positional;
   if (!resourceType || !resourceId) {
-    log.err('Usage: draftgo diff <pages|nav|docs> <id>');
+    log.err('Usage: draftgo diff <pages|nav|docs|services> <id>');
     return 1;
   }
   const result = diffResource(projectDir, resourceType, resourceId);

package/src/commands/help.js

@@ -18,7 +18,7 @@ Tailwind CSS 4, and the DraftGo built-in component library (draftgo/*).
 Provider brands and shared icons are served from the local /assets/providers and
 /assets/icons directories; the Page runtime does not require third-party CDNs.
 System MCP handles live discovery and structured resources; complete page,
-navigation, and document bodies use checkout/commit outside MCP context.
+  navigation, document, and Go source bodies use checkout/commit outside MCP context.
 The installed Skill routes agents to task-specific References and MCP tools.
 
 Usage:
@@ -113,7 +113,7 @@ Usage:
   draftgo -h | --help              Show this help.
 
 Resource types:
-  pages | nav/navigations | docs/articles
+  pages | nav/navigations | docs/articles | services
 
 Important flags:
   --project <dir>          Operate on <dir> instead of the current directory.
@@ -134,8 +134,8 @@ Important flags:
   --output json            Print machine-readable output where supported.
   --type <type>            (map) pages | nav/navigations | docs/articles;
                            (capabilities) alias for a Registry module filter.
-  --route <path>           (map) Select resources with this exact route.
-  --title <title>          (map) Select resources with this exact title.
+  --route <path>           (map/checkout) Select resources with this exact route.
+  --title <title>          (map/checkout) Select resources with this exact title.
   --limit <1-100>          (map) Maximum resources returned per type/page;
                            defaults to 20.
   --cursor <cursor>        (map) Continue one typed map result page.

package/src/commands/reconcile.js

@@ -6,7 +6,7 @@ const { reconcileResources } = require('../worktree');
 async function reconcile(projectDir, positional, flags = {}) {
   const [resourceType, ...ids] = positional;
   if (!resourceType || !ids.length) {
-    log.err('Usage: draftgo reconcile <pages|nav|docs> <id...>');
+    log.err('Usage: draftgo reconcile <pages|nav|docs|services> <id...>');
     return 1;
   }
   const results = await reconcileResources(projectDir, resourceType, ids);

package/src/worktree/backend.js

@@ -1,6 +1,8 @@
 'use strict';
 
+const crypto = require('crypto');
 const fs = require('fs');
+const path = require('path');
 const { Readable } = require('stream');
 const { DraftGoMcpClient } = require('../mcp/client');
 const { BackendHttpError, WorktreeError } = require('./errors');
@@ -15,8 +17,21 @@ 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 }),
+  services: Object.freeze({
+    checkout: 'listCustomServiceDraft',
+    commit: 'updateCustomServiceDraft',
+    contentType: 'text/plain; charset=utf-8',
+    jsonCommit: true,
+    commitField: 'source',
+    fileExtension: '.go',
+    sdk: 'listCustomServiceSdk',
+  }),
 });
 
+function sha256Utf8(value) {
+  return crypto.createHash('sha256').update(String(value), 'utf8').digest('hex');
+}
+
 function isObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -184,29 +199,126 @@ async function finalMetadata(config, resourceType, resourceId, session, options
   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');
+  if (type === 'services' && typeof value.source !== 'string') {
+    throw new WorktreeError('INVALID_BACKEND_RESPONSE', 'DraftGo service draft did not include source text.');
+  }
   const version = firstValue(value.content_version, value.revision);
-  const content = typeof value.content === 'string' ? value.content : null;
+  const sourceContent = type === 'services' ? value.source : null;
+  const content = sourceContent != null
+    ? sourceContent
+    : (typeof value.content === 'string' ? value.content : null);
   const contentURL = firstValue(value.content_url, checkoutURL);
-  const contentType = type === 'docs' ? spec.contentType : spec.contentType;
+  const contentType = spec.contentType;
   const size = content == null ? null : Buffer.byteLength(content, 'utf8');
+  const contentHash = sourceContent != null ? sha256Utf8(sourceContent) : value.content_hash;
+  const usesRevision = type === 'docs' || type === 'services';
   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',
+    file_extension: spec.fileExtension || '.html',
     content_size: size,
-    content_hash: value.content_hash,
-    ...(type === 'docs' ? { base_revision: version } : { base_version: version }),
-    etag: value.content_hash,
+    content_hash: contentHash,
+    ...(usesRevision ? { base_revision: version } : { base_version: version }),
+    etag: contentHash,
     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,
+    commit_field: spec.commitField || null,
   });
 }
 
+function sdkRelativePath(value) {
+  const relative = String(value || '').replace(/\\/g, '/').replace(/^\/+/, '');
+  if (!relative || relative.includes('\0') || relative.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+    throw new WorktreeError('UNSAFE_SDK_PATH', 'DraftGo SDK bundle included an unsafe relative path.', { path: value });
+  }
+  return relative;
+}
+
+async function syncSDK(config, session, projectDir, options = {}) {
+  const { registryRevision, describeOperation } = require('../commands/api');
+  const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
+  const spec = FINAL_OPERATIONS.services;
+  const sdkDir = path.join(projectDir, '.draftgo', 'worktree', 'sdk');
+  let apiSession;
+  try {
+    apiSession = session && session.names && session.names[TOOL_NAMES.apiCall]
+      ? session
+      : await openToolSession(config, [
+        TOOL_NAMES.apiSearch, TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall,
+      ], {
+        ...options,
+        client: (session && session.client) || options.client,
+        tools: (session && session.tools) || options.tools,
+        clientInitialized: true,
+      });
+  } catch (error) {
+    throw new WorktreeError(
+      'SDK_CHECKOUT_FAILED',
+      `Unable to open an API session for the Go SDK bundle: ${error.message}`,
+    );
+  }
+  let revision;
+  let described;
+  try {
+    revision = await registryRevision(apiSession, spec.sdk);
+    described = await describeOperation(projectDir || process.cwd(), config, apiSession, spec.sdk, revision);
+  } catch (error) {
+    throw new WorktreeError(
+      'SDK_CHECKOUT_FAILED',
+      `Unable to describe the Go SDK bundle (${spec.sdk}): ${error.message}`,
+    );
+  }
+  const operation = described && described.operation || {};
+  const invoke = await callStructured(apiSession, TOOL_NAMES.apiCall, {
+    operation_id: spec.sdk,
+    registry_revision: revision,
+  }, options);
+  const workflow = invoke && invoke.workflow || {};
+  if (workflow.required !== true || workflow.workflow !== 'checkout_commit') {
+    throw new WorktreeError('INVALID_WORKFLOW_DESCRIPTOR', 'DraftGo did not return a checkout/commit workflow descriptor for the Go SDK bundle.');
+  }
+  const sdkURL = operationPath(config, operation.path || workflow.path, '');
+  const response = await (options.fetch || fetch)(sdkURL, {
+    method: String(operation.method || 'GET').toUpperCase(),
+    headers: authHeaders(config, { Accept: 'application/json' }),
+    signal: options.signal,
+    redirect: 'error',
+  });
+  if (!response.ok) {
+    const httpError = await errorForResponse(response, config.token || config.sat);
+    throw new WorktreeError(
+      'SDK_CHECKOUT_FAILED',
+      `Unable to download the Go SDK bundle: ${httpError.message}`,
+      { status: httpError.status, code: httpError.code },
+    );
+  }
+  const raw = await readBounded(response, MAX_CHECKOUT_JSON_BYTES, true);
+  const value = parseJsonText(raw, 'DraftGo SDK endpoint');
+  const files = isObject(value.files) ? value.files : null;
+  if (!files || !Object.keys(files).length) {
+    throw new WorktreeError('SDK_CHECKOUT_FAILED', 'DraftGo SDK bundle did not include any files.');
+  }
+  await fs.promises.rm(sdkDir, { recursive: true, force: true });
+  await fs.promises.mkdir(sdkDir, { recursive: true });
+  for (const [relative, content] of Object.entries(files)) {
+    const safe = sdkRelativePath(relative);
+    const destination = path.join(sdkDir, ...safe.split('/'));
+    if (typeof content !== 'string') {
+      throw new WorktreeError('SDK_CHECKOUT_FAILED', `DraftGo SDK file ${safe} is not text.`);
+    }
+    await fs.promises.mkdir(path.dirname(destination), { recursive: true });
+    await fs.promises.writeFile(destination, content, 'utf8');
+  }
+  const contentHash = firstValue(value.content_hash, sha256Utf8(JSON.stringify(files)));
+  await fs.promises.writeFile(path.join(sdkDir, '.hash'), `${contentHash}\n`, 'utf8');
+  return { directory: sdkDir, content_hash: contentHash };
+}
+
 function normalizeUrl(config, value, purpose) {
   if (!value) return null;
   let url;
@@ -281,8 +393,16 @@ function normalizeMetadata(config, resourceType, resourceId, payload) {
 
 async function resolveMetadata(config, resourceType, resourceId, options = {}) {
   if (options.metadata) return normalizeMetadata(config, resourceType, resourceId, options.metadata);
+  const type = canonicalResourceType(resourceType);
   const client = options.client || new DraftGoMcpClient(config);
   if (!options.clientInitialized) await client.initialize(options);
+  if (type === 'services') {
+    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, type, resourceId, session, options);
+  }
   let toolName = METADATA_TOOL;
   if (typeof client.listAllTools === 'function') {
     const tools = options.tools || await client.listAllTools(options);
@@ -382,21 +502,29 @@ async function commit(config, metadata, localPath, current, options = {}) {
     '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 } : {}),
-    });
+  const raw = metadata.raw && typeof metadata.raw === 'object' ? metadata.raw : {};
+  const commitField = raw.commitField || raw.commit_field || null;
+  if (commitField !== 'source') {
+    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);
+  if (raw.json_commit === true) {
+    const fileContents = fs.readFileSync(localPath, 'utf8');
+    body = JSON.stringify(commitField === 'source'
+      ? {
+        source: fileContents,
+        ...(metadata.base_revision != null ? { base_revision: metadata.base_revision } : {}),
+      }
+      : {
+        content: fileContents,
+        ...(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 {
@@ -413,8 +541,14 @@ async function commit(config, metadata, localPath, current, options = {}) {
   });
   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');
+  if (!text.trim()) {
+    return commitField === 'source' ? { content_hash: current.hash } : {};
+  }
+  const payload = parseJsonText(text, 'DraftGo commit endpoint');
+  if (commitField === 'source') {
+    return { ...payload, content_hash: current.hash };
+  }
+  return payload;
 }
 
 function nodeReadable(response) {
@@ -424,6 +558,7 @@ function nodeReadable(response) {
 
 module.exports = {
   METADATA_TOOL,
+  FINAL_OPERATIONS,
   readBounded,
   MAX_CHECKOUT_JSON_BYTES,
   toolNameMatches,
@@ -433,6 +568,7 @@ module.exports = {
   resolveMetadata,
   download,
   commit,
+  syncSDK,
   nodeReadable,
   errorForResponse,
 };

package/src/worktree/index.js

@@ -163,6 +163,9 @@ async function checkoutResourcesUnlocked(projectDir, resourceType, resourceIds,
     return entry;
   }, { ...options, settled: true });
   const results = settled.filter((item) => item.status === 'fulfilled').map((item) => item.value);
+  if (canonical === 'services' && results.length && typeof backend.syncSDK === 'function') {
+    await backend.syncSDK(config, session, projectDir, { ...options, ...session, projectDir });
+  }
   for (const entry of results) manifest.entries[entryKey(canonical, entry.resource_id)] = entry;
   if (results.length) await saveManifest(projectDir, manifest);
   const failures = settled.filter((item) => item.status === 'rejected');

package/src/worktree/types.js

@@ -7,6 +7,7 @@ const RESOURCE_TYPES = Object.freeze({
   pages: Object.freeze({ directory: 'pages', prefix: 'page' }),
   navigations: Object.freeze({ directory: 'navigations', prefix: 'nav' }),
   docs: Object.freeze({ directory: 'docs', prefix: 'article' }),
+  services: Object.freeze({ directory: 'services', prefix: 'service' }),
 });
 
 const TYPE_ALIASES = new Map([
@@ -20,6 +21,8 @@ const TYPE_ALIASES = new Map([
   ['article', 'docs'],
   ['articles', 'docs'],
   ['docs/articles', 'docs'],
+  ['service', 'services'],
+  ['services', 'services'],
 ]);
 
 const CONTENT_EXTENSIONS = new Map([
@@ -28,6 +31,7 @@ const CONTENT_EXTENSIONS = new Map([
   ['text/markdown', '.md'],
   ['text/x-markdown', '.md'],
   ['text/plain', '.txt'],
+  ['text/x-go', '.go'],
 ]);
 
 function canonicalResourceType(value) {
@@ -36,7 +40,7 @@ function canonicalResourceType(value) {
   if (!canonical) {
     throw new WorktreeError(
       'UNSUPPORTED_RESOURCE_TYPE',
-      `Unsupported checkout resource type: ${value}. Expected pages, nav, or docs.`,
+      `Unsupported checkout resource type: ${value}. Expected pages, nav, docs, or services.`,
       { resource_type: value }
     );
   }
@@ -48,25 +52,25 @@ function mediaType(contentType) {
 }
 
 function normalizeExtension(contentType, backendExtension) {
+  if (backendExtension != null && backendExtension !== '') {
+    let extension = String(backendExtension).trim();
+    if (!extension.startsWith('.')) extension = `.${extension}`;
+    if (!/^\.[A-Za-z0-9][A-Za-z0-9._-]{0,15}$/.test(extension)) {
+      throw new WorktreeError(
+        'UNSAFE_FILE_EXTENSION',
+        'The backend returned an unsafe checkout file extension.',
+        { file_extension: backendExtension }
+      );
+    }
+    return extension.toLowerCase();
+  }
   const known = CONTENT_EXTENSIONS.get(mediaType(contentType));
   if (known) return known;
-  if (backendExtension == null || backendExtension === '') {
-    throw new WorktreeError(
-      'MISSING_FILE_EXTENSION',
-      'DraftGo must provide a safe file extension for this content type.',
-      { content_type: contentType },
-    );
-  }
-  let extension = String(backendExtension).trim();
-  if (!extension.startsWith('.')) extension = `.${extension}`;
-  if (!/^\.[A-Za-z0-9][A-Za-z0-9._-]{0,15}$/.test(extension)) {
-    throw new WorktreeError(
-      'UNSAFE_FILE_EXTENSION',
-      'The backend returned an unsafe checkout file extension.',
-      { file_extension: backendExtension }
-    );
-  }
-  return extension.toLowerCase();
+  throw new WorktreeError(
+    'MISSING_FILE_EXTENSION',
+    'DraftGo must provide a safe file extension for this content type.',
+    { content_type: contentType },
+  );
 }
 
 function safeIdSegment(value) {