draftgo-cli 4.0.1 → 4.0.22

package/src/commands/components.js

@@ -0,0 +1,550 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const AdmZip = require('adm-zip');
+const parse5 = require('parse5');
+const log = require('../logger');
+const { loadProjectConfig } = require('../projectConfig');
+const { loadManifest, getEntry, absolutePath } = require('../worktree/manifest');
+
+async function request(config, method, route, body) {
+  const multipart = typeof FormData !== 'undefined' && body instanceof FormData;
+  const response = await fetch(`${config.server}/api/${route.replace(/^\//, '')}`, {
+    method,
+    headers: { Authorization: `Bearer ${config.token}`, ...(multipart ? {} : { 'Content-Type': 'application/json' }) },
+    body: body === undefined ? undefined : (multipart ? body : JSON.stringify(body)),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(payload.message || payload.error?.message || `DraftGo API ${response.status}`);
+  return payload.data ?? payload;
+}
+
+function componentName(item) {
+  return item.full_name || `${item.library_slug}/${item.slug}`;
+}
+
+async function findComponent(config, name) {
+  if (!name) throw new Error('Component name must be <library/component>.');
+  const [library, slug] = String(name).split('/');
+  if (!library || !slug) throw new Error('Component name must be <library/component>.');
+  const result = await request(config, 'GET', `components?library=${encodeURIComponent(library)}&q=${encodeURIComponent(slug)}&page_size=100`);
+  const item = (result.items || []).find(value => componentName(value) === name || (value.library_slug === library && value.slug === slug));
+  if (!item) throw new Error(`Component not found: ${name}`);
+  return request(config, 'GET', `components/${item.id}`);
+}
+
+function readJSON(projectDir, file) {
+  if (!file) return {};
+  return JSON.parse(fs.readFileSync(path.resolve(projectDir, String(file)), 'utf8'));
+}
+
+function csv(value) {
+  return value ? String(value).split(',').map(item => item.trim()).filter(Boolean) : undefined;
+}
+
+function normalizeDefinition(definition = {}) {
+  return {
+    html: definition.html || '', css: definition.css || '', js: definition.js || '',
+    props: definition.props || [], slots: definition.slots || [], css_variables: definition.css_variables || [],
+    events: definition.events || [], dependencies: definition.dependencies || [], examples: definition.examples || [],
+    usage: definition.usage || '', root_tag: definition.root_tag || '', meta: definition.meta || {},
+  };
+}
+
+function definitionHash(definition) {
+  return crypto.createHash('sha256').update(JSON.stringify(normalizeDefinition(definition))).digest('hex');
+}
+
+function componentDir(projectDir, name) {
+  const [library, slug] = String(name).split('/');
+  if (!library || !slug || !/^[a-z0-9-]+$/.test(library) || !/^[a-z0-9-]+$/.test(slug)) {
+    throw new Error('Component name must be a safe <library/component> slug.');
+  }
+  return path.join(projectDir, '.draftgo', 'worktree', 'components', library, slug);
+}
+
+function contractFrom(definition = {}) {
+  const { props, slots, css_variables, events, dependencies, examples, usage, root_tag, meta } = normalizeDefinition(definition);
+  return { props, slots, css_variables, events, dependencies, examples, usage, root_tag, meta };
+}
+
+function localDefinition(directory) {
+  const contract = JSON.parse(fs.readFileSync(path.join(directory, 'contract.json'), 'utf8'));
+  return normalizeDefinition({
+    html: fs.readFileSync(path.join(directory, 'component.html'), 'utf8'),
+    css: fs.readFileSync(path.join(directory, 'component.css'), 'utf8'),
+    js: fs.readFileSync(path.join(directory, 'component.js'), 'utf8'),
+    ...contract,
+  });
+}
+
+function writeComponentFiles(directory, item) {
+  fs.mkdirSync(directory, { recursive: true });
+  fs.writeFileSync(path.join(directory, 'component.html'), item.draft.html || '', 'utf8');
+  fs.writeFileSync(path.join(directory, 'component.css'), item.draft.css || '', 'utf8');
+  fs.writeFileSync(path.join(directory, 'component.js'), item.draft.js || '', 'utf8');
+  fs.writeFileSync(path.join(directory, 'contract.json'), `${JSON.stringify(contractFrom(item.draft), null, 2)}\n`, 'utf8');
+  const metadata = {
+    id: item.id, library_id: item.library_id, library_slug: item.library_slug,
+    name: item.name, slug: item.slug, category: item.category || '', description: item.description || '',
+    tags: item.tags || [], status: item.status || 'active', published_revision: item.published_revision || 0,
+    remote_draft_hash: definitionHash(item.draft), updated_at: item.updated_at,
+  };
+  fs.writeFileSync(path.join(directory, 'component.json'), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+  fs.writeFileSync(path.join(directory, '.base.json'), `${JSON.stringify(item, null, 2)}\n`, 'utf8');
+}
+
+function output(value, flags, title) {
+  if (flags.output === 'json') console.log(JSON.stringify(value, null, 2));
+  else if (Array.isArray(value)) { log.title(title); value.forEach(item => log.plain(`  ${item.name || item.slug || item}`)); }
+  else console.log(JSON.stringify(value, null, 2));
+}
+
+async function search(projectDir, query, flags) {
+  if (!query) throw new Error('Usage: draftgo components search <query>');
+  const config = loadProjectConfig(projectDir);
+  const result = await request(config, 'GET', `components?q=${encodeURIComponent(query)}&page_size=100`);
+  output(result.items || result, flags, `DraftGo components: ${query}`);
+  return 0;
+}
+
+async function show(projectDir, name, flags) {
+  if (!name) throw new Error('Usage: draftgo components show <library/component>');
+  const config = loadProjectConfig(projectDir);
+  const slug = String(name).split('/').pop();
+  const result = await request(config, 'GET', `components?q=${encodeURIComponent(slug)}&page_size=100`);
+  const item = (result.items || []).find(component => `${component.library_slug}/${component.slug}` === name || component.slug === slug);
+  if (!item) throw new Error(`Component not found: ${name}`);
+  output(item, flags, `DraftGo component ${name}`);
+  return 0;
+}
+
+async function list(projectDir, flags) {
+  const config = loadProjectConfig(projectDir);
+  const query = new URLSearchParams({ page_size: '100' });
+  if (flags.library) query.set('library', String(flags.library));
+  if (flags.status) query.set('status', String(flags.status));
+  const result = await request(config, 'GET', `components?${query}`);
+  output(result.items || result, flags, 'DraftGo components');
+  return 0;
+}
+
+async function libraries(projectDir, positional, flags) {
+  const action = String(positional[0] || 'list').toLowerCase();
+  const config = loadProjectConfig(projectDir);
+  const items = async () => (await request(config, 'GET', 'component-libraries')).items || [];
+  const find = async value => {
+    const item = (await items()).find(candidate => String(candidate.id) === String(value) || candidate.slug === value);
+    if (!item) throw new Error(`Component library not found: ${value}`);
+    return item;
+  };
+  if (action === 'list') { output(await items(), flags, 'DraftGo component libraries'); return 0; }
+  if (action === 'show') { output(await find(positional[1]), flags, `Component library ${positional[1]}`); return 0; }
+  if (action === 'delete') {
+    const item = await find(positional[1]);
+    output(await request(config, 'DELETE', `component-libraries/${item.id}`), flags, 'Component library deleted');
+    return 0;
+  }
+  if (action === 'create' || action === 'update') {
+    const current = action === 'update' ? await find(positional[1]) : {};
+    const input = { ...current, ...readJSON(projectDir, flags.file) };
+    for (const [flag, key] of [['name', 'name'], ['slug', 'slug'], ['description', 'description'], ['source-type', 'source_type'], ['status', 'status']]) {
+      if (flags[flag] !== undefined) input[key] = flags[flag];
+    }
+    const result = await request(config, action === 'create' ? 'POST' : 'PUT',
+      action === 'create' ? 'component-libraries' : `component-libraries/${current.id}`, input);
+    output(result, flags, `Component library ${action}d`);
+    return 0;
+  }
+  throw new Error('Usage: draftgo components libraries list|show|create|update|delete');
+}
+
+async function create(projectDir, flags) {
+  const config = loadProjectConfig(projectDir);
+  const library = (await request(config, 'GET', 'component-libraries')).items
+    .find(item => String(item.id) === String(flags.library) || item.slug === flags.library);
+  if (!library) throw new Error('Usage: draftgo components create --library <id|slug> --name <name> --slug <slug> [--file input.json]');
+  const fileInput = readJSON(projectDir, flags.file);
+  const input = {
+    ...fileInput, library_id: library.id,
+    name: flags.name || fileInput.name, slug: flags.slug || fileInput.slug,
+    category: flags.category ?? fileInput.category ?? '', description: flags.description ?? fileInput.description ?? '',
+    tags: csv(flags.tags) || fileInput.tags || [], status: flags.status || fileInput.status || 'active',
+    draft: fileInput.draft || { html: '<div></div>', root_tag: 'div' },
+  };
+  const item = await request(config, 'POST', 'components', input);
+  output(item, flags, 'Component created');
+  return 0;
+}
+
+async function remove(projectDir, name, flags) {
+  const config = loadProjectConfig(projectDir);
+  const item = await findComponent(config, name);
+  const confirm = flags.yes || flags.y ? '?confirm=1' : '';
+  output(await request(config, 'DELETE', `components/${item.id}${confirm}`), flags, 'Component deleted');
+  return 0;
+}
+
+async function copy(projectDir, source, flags) {
+  const config = loadProjectConfig(projectDir);
+  const item = await findComponent(config, source);
+  const librariesResult = await request(config, 'GET', 'component-libraries');
+  const library = librariesResult.items.find(value => value.slug === (flags.library || item.library_slug));
+  if (!library || !flags.slug) throw new Error('Usage: draftgo components copy <library/component> --slug <new-slug> [--library slug] [--name name]');
+  const created = await request(config, 'POST', 'components', {
+    library_id: library.id, name: flags.name || `${item.name} Copy`, slug: flags.slug,
+    category: item.category, description: item.description, tags: item.tags, draft: item.draft, status: item.status,
+  });
+  output(created, flags, 'Component copied');
+  return 0;
+}
+
+async function checkout(projectDir, name, flags) {
+  const config = loadProjectConfig(projectDir);
+  const item = await findComponent(config, name);
+  const directory = componentDir(projectDir, componentName(item));
+  if (fs.existsSync(path.join(directory, '.base.json')) && !flags.force) {
+    const base = JSON.parse(fs.readFileSync(path.join(directory, '.base.json'), 'utf8'));
+    if (definitionHash(localDefinition(directory)) !== definitionHash(base.draft)) {
+      throw new Error(`Local changes present for ${name}; commit them or use --force.`);
+    }
+  }
+  writeComponentFiles(directory, item);
+  output({ component: componentName(item), directory: path.relative(projectDir, directory).replace(/\\/g, '/') }, flags, 'Component checked out');
+  return 0;
+}
+
+function localState(projectDir, name) {
+  const directory = componentDir(projectDir, name);
+  if (!fs.existsSync(path.join(directory, '.base.json'))) throw new Error(`${name} is not checked out.`);
+  return {
+    directory,
+    base: JSON.parse(fs.readFileSync(path.join(directory, '.base.json'), 'utf8')),
+    metadata: JSON.parse(fs.readFileSync(path.join(directory, 'component.json'), 'utf8')),
+    definition: localDefinition(directory),
+  };
+}
+
+async function diff(projectDir, name, flags) {
+  const config = loadProjectConfig(projectDir);
+  const state = localState(projectDir, name);
+  const remote = await findComponent(config, name);
+  const sections = ['html', 'css', 'js', 'props', 'slots', 'css_variables', 'events', 'dependencies', 'examples', 'usage', 'root_tag', 'meta'];
+  const changed = (left, right) => {
+    const normalizedLeft = normalizeDefinition(left);
+    const normalizedRight = normalizeDefinition(right);
+    return sections.filter(key => JSON.stringify(normalizedLeft[key]) !== JSON.stringify(normalizedRight[key]));
+  };
+  const result = {
+    component: name, local_vs_base: changed(state.definition, state.base.draft),
+    local_vs_remote_draft: changed(state.definition, remote.draft),
+    local_vs_published: changed(state.definition, remote.published),
+    base_remote_changed: definitionHash(state.base.draft) !== definitionHash(remote.draft),
+    published_revision: remote.published_revision || 0,
+  };
+  output(result, flags, `Component diff ${name}`);
+  return 0;
+}
+
+function verifyDefinition(definition) {
+  const errors = [];
+  const fragment = parse5.parseFragment(definition.html || '');
+  const roots = fragment.childNodes.filter(node => node.nodeName !== '#text' || String(node.value || '').trim());
+  const elements = roots.filter(node => node.nodeName !== '#text' && node.nodeName !== '#comment');
+  if (elements.length !== 1 || roots.some(node => node.nodeName === '#text')) errors.push('HTML must contain exactly one root element.');
+  const rootTag = elements[0]?.tagName || elements[0]?.nodeName;
+  if (definition.root_tag && definition.root_tag.toLowerCase() !== rootTag) errors.push('root_tag does not match the HTML root.');
+  const propNames = new Set();
+  for (const prop of definition.props || []) {
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(prop.name || '') || propNames.has(prop.name)) errors.push(`Invalid or duplicate prop: ${prop.name || '(empty)'}`);
+    if (!['string', 'boolean', 'number'].includes(prop.type || 'string')) errors.push(`Invalid prop type: ${prop.type}`);
+    propNames.add(prop.name);
+  }
+  if (!Array.isArray(definition.dependencies || [])) errors.push('dependencies must be an array.');
+  for (const example of definition.examples || []) {
+    if (!example.name || !example.html) errors.push('Each example requires name and html.');
+  }
+  return errors;
+}
+
+async function verify(projectDir, name, flags) {
+  const config = loadProjectConfig(projectDir);
+  const state = localState(projectDir, name);
+  const errors = verifyDefinition(state.definition);
+  for (const dependency of state.definition.dependencies || []) {
+    try { await findComponent(config, dependency); } catch { errors.push(`Dependency not found: ${dependency}`); }
+  }
+  const result = { component: name, valid: errors.length === 0, errors };
+  output(result, flags, `Component verify ${name}`);
+  if (errors.length) throw new Error(`Component verification failed with ${errors.length} error(s).`);
+  return 0;
+}
+
+async function commit(projectDir, name, flags) {
+  const config = loadProjectConfig(projectDir);
+  const state = localState(projectDir, name);
+  const errors = verifyDefinition(state.definition);
+  for (const dependency of state.definition.dependencies || []) {
+    try { await findComponent(config, dependency); } catch { errors.push(`Dependency not found: ${dependency}`); }
+  }
+  if (errors.length) throw new Error(`Component verification failed: ${errors.join(' ')}`);
+  const remote = await findComponent(config, name);
+  if (definitionHash(remote.draft) !== definitionHash(state.base.draft)) {
+    throw new Error(`Remote draft changed after checkout for ${name}; run components checkout after preserving local changes.`);
+  }
+  if (definitionHash(state.definition) === definitionHash(remote.draft)
+      && ['name', 'slug', 'category', 'description', 'tags', 'status'].every(key => JSON.stringify(state.metadata[key] ?? null) === JSON.stringify(remote[key] ?? null))) {
+    writeComponentFiles(state.directory, remote);
+    output({ component: name, status: 'unchanged' }, flags, 'Component draft unchanged');
+    return 0;
+  }
+  const metadata = state.metadata;
+  const result = await request(config, 'PUT', `components/${remote.id}`, {
+    library_id: remote.library_id, name: metadata.name, slug: metadata.slug, category: metadata.category || '',
+    description: metadata.description || '', tags: metadata.tags || [], status: metadata.status || 'active', draft: state.definition,
+  });
+  writeComponentFiles(state.directory, result);
+  output(result, flags, 'Component draft committed');
+  return 0;
+}
+
+async function publish(projectDir, name, flags) {
+  const config = loadProjectConfig(projectDir);
+  const remote = await findComponent(config, name);
+  const state = localState(projectDir, name);
+  if (definitionHash(state.definition) !== definitionHash(remote.draft)) {
+    throw new Error('Local component differs from the remote draft; commit before publish.');
+  }
+  const result = await request(config, 'POST', `components/${remote.id}/publish`, {});
+  writeComponentFiles(state.directory, result);
+  output(result, flags, 'Component published');
+  return 0;
+}
+
+async function importZIP(projectDir, file, flags) {
+  if (!file) throw new Error('Usage: draftgo components import <zip-file> [--dry-run]');
+  const config = loadProjectConfig(projectDir);
+  const absolute = path.resolve(projectDir, file);
+  const form = new FormData();
+  form.append('file', new Blob([fs.readFileSync(absolute)]), path.basename(absolute));
+  const result = await request(config, 'POST', `component-libraries/import${flags['dry-run'] ? '?dry_run=1' : ''}`, form);
+  output(result, flags, flags['dry-run'] ? 'Component import preview' : 'Components imported');
+  return 0;
+}
+
+async function exportZIP(projectDir, librarySlug, flags) {
+  if (!librarySlug) throw new Error('Usage: draftgo components export <library> --file <zip-file>');
+  const config = loadProjectConfig(projectDir);
+  const librariesResult = await request(config, 'GET', 'component-libraries');
+  const library = librariesResult.items.find(item => item.slug === librarySlug || String(item.id) === String(librarySlug));
+  if (!library) throw new Error(`Component library not found: ${librarySlug}`);
+  const components = [];
+  for (let page = 1; ; page += 1) {
+    const result = await request(config, 'GET', `components?library=${encodeURIComponent(library.slug)}&page=${page}&page_size=100`);
+    components.push(...(result.items || []));
+    if ((result.items || []).length < 100) break;
+  }
+  const zip = new AdmZip();
+  const manifest = {
+    library: { name: library.name, slug: library.slug, description: library.description, source_type: 'imported', common_css: 'library/common.css', common_js: 'library/common.js', assets: [], status: library.status },
+    components: [],
+  };
+  zip.addFile('library/common.css', Buffer.from(library.common_css || '', 'utf8'));
+  zip.addFile('library/common.js', Buffer.from(library.common_js || '', 'utf8'));
+  for (const [index, asset] of (library.assets || []).entries()) {
+    const url = new URL(String(asset), `${config.server}/`);
+    const response = await fetch(url, { headers: url.origin === new URL(config.server).origin ? { Authorization: `Bearer ${config.token}` } : {} });
+    if (!response.ok) throw new Error(`Unable to export component asset ${asset}: HTTP ${response.status}`);
+    const base = path.posix.basename(url.pathname) || `asset-${index + 1}`;
+    const archivePath = `library/assets/${index + 1}-${base.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+    zip.addFile(archivePath, Buffer.from(await response.arrayBuffer()));
+    manifest.library.assets.push(archivePath);
+  }
+  for (const summary of components) {
+    const item = await request(config, 'GET', `components/${summary.id}`);
+    const definition = `components/${item.slug}.json`;
+    manifest.components.push({ name: item.name, slug: item.slug, category: item.category, description: item.description, tags: item.tags, definition });
+    zip.addFile(definition, Buffer.from(`${JSON.stringify(item.draft, null, 2)}\n`, 'utf8'));
+  }
+  zip.addFile('draftgo-components.json', Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, 'utf8'));
+  const destination = path.resolve(projectDir, flags.file || `${library.slug}-components.zip`);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  zip.writeZip(destination);
+  output({ library: library.slug, components: manifest.components.length, file: path.relative(projectDir, destination).replace(/\\/g, '/') }, flags, 'Component library exported');
+  return 0;
+}
+
+function walk(node, visit) {
+  if (!node) return null;
+  if (visit(node)) return node;
+  for (const child of node.childNodes || []) { const found = walk(child, visit); if (found) return found; }
+  return null;
+}
+
+function cloneNode(node, parentNode = null) {
+  const copy = { ...node };
+  if (node.attrs) copy.attrs = node.attrs.map(attr => ({ ...attr }));
+  if (node.childNodes) {
+    copy.childNodes = node.childNodes.map(child => cloneNode(child, copy));
+  }
+  if (parentNode) copy.parentNode = parentNode;
+  return copy;
+}
+
+function escapeScript(value) {
+  return String(value || '').replace(/<\/script/gi, '<\\/script').replace(/<!--/g, '<\\!--');
+}
+
+function fillSlots(root, target) {
+  const supplied = new Map();
+  for (const child of target.childNodes || []) {
+    const marker = child.attrs?.find(attr => attr.name === 'data-dg-slot');
+    const slot = marker?.value || 'default';
+    if (!supplied.has(slot)) supplied.set(slot, []);
+    if (marker) supplied.get(slot).push(...(child.childNodes || []).map(node => cloneNode(node)));
+    else supplied.get(slot).push(cloneNode(child));
+  }
+  walk(root, node => {
+    const marker = node.attrs?.find(attr => attr.name === 'data-dg-slot-target');
+    if (!marker) return false;
+    const name = marker.value || 'default';
+    const nodes = supplied.get(name) || [];
+    if (nodes.length) {
+      node.childNodes = nodes.map(child => {
+        const copy = cloneNode(child, node);
+        if (copy.attrs) copy.attrs = copy.attrs.filter(attr => attr.name !== 'data-dg-slot');
+        return copy;
+      });
+    }
+    node.attrs = node.attrs.filter(attr => attr.name !== 'data-dg-slot-target');
+    return false;
+  });
+}
+
+function expandHtml(source, instance, component, runtimeCatalog = null) {
+  const document = parse5.parse(source, { sourceCodeLocationInfo: true });
+  const target = walk(document, node => node.attrs?.some(attr => attr.name === 'data-dg-instance' && attr.value === instance));
+  if (!target) throw new Error(`data-dg-instance not found: ${instance}`);
+  const definition = component.published || component.draft;
+  const template = parse5.parseFragment(definition?.html || '');
+  const root = template.childNodes.find(node => node.nodeName !== '#text');
+  if (!root) throw new Error('Component definition has no root HTML element.');
+  if (target.nodeName !== root.nodeName) throw new Error(`root tag must be <${root.nodeName}>`);
+  const originalAttrs = new Map((target.attrs || []).map(attr => [attr.name, attr.value]));
+  const props = {};
+  const slots = {};
+  for (const child of target.childNodes || []) {
+    const marker = child.attrs?.find(attr => attr.name === 'data-dg-slot');
+    const slot = marker?.value || 'default';
+    const content = marker ? (child.childNodes || []).map(node => parse5.serialize(node)).join('') : parse5.serialize(child);
+    slots[slot] = (slots[slot] || '') + content;
+  }
+  for (const prop of definition.props || []) {
+    const raw = originalAttrs.get(`data-dg-prop-${prop.name}`);
+    if (raw === undefined) props[prop.name] = prop.default;
+    else if (prop.type === 'boolean') props[prop.name] = raw === '' || raw === 'true' || raw === '1';
+    else if (prop.type === 'number') props[prop.name] = Number.isFinite(Number(raw)) ? Number(raw) : prop.default;
+    else props[prop.name] = raw;
+  }
+  fillSlots(root, target);
+  const replacement = root;
+  replacement.attrs = replacement.attrs || [];
+  const attrMap = new Map(replacement.attrs.map(attr => [attr.name, attr.value]));
+  for (const [name, value] of originalAttrs) {
+    if (name === 'class') continue;
+    if (name === 'data-dg-use' || name.startsWith('data-dg-prop-')) continue;
+    if (name === 'data-dg-slot') continue;
+    // Page-owned attributes win over template defaults, just like the live
+    // browser runtime. This preserves ids, names, type, aria and business
+    // data attributes when an instance is expanded.
+    attrMap.set(name, value);
+  }
+  attrMap.set('data-dg-expanded-instance', instance);
+  attrMap.set('class', [...new Set(`${attrMap.get('class') || ''} ${originalAttrs.get('class') || ''}`.split(/\s+/).filter(Boolean))].join(' '));
+  replacement.attrs = [...attrMap].map(([name, value]) => ({ name, value }));
+  target.nodeName = replacement.nodeName;
+  target.tagName = replacement.tagName;
+  target.attrs = replacement.attrs || [];
+  target.childNodes = replacement.childNodes || [];
+  target.childNodes.forEach(node => { node.parentNode = target; });
+  const css = (definition?.css || '').replaceAll(`[data-dg-use="${component.library_slug}/${component.slug}"]`, `[data-dg-expanded-instance="${instance}"]`).replaceAll(`[data-dg-use='${component.library_slug}/${component.slug}']`, `[data-dg-expanded-instance="${instance}"]`);
+  const js = definition?.js || '';
+  const libraries = runtimeCatalog?.libraries || [];
+  const libraryCSS = libraries.map(library => library.common_css || '').filter(Boolean).join('\n');
+  const dependencyCSS = (runtimeCatalog?.components || [])
+    .filter(item => item.name !== (component.full_name || `${component.library_slug}/${component.slug}`))
+    .map(item => item.definition?.css || '')
+    .filter(Boolean)
+    .join('\n');
+  const assets = libraries.flatMap(library => library.assets || []).filter(Boolean);
+  const assetLinks = assets.map(value => {
+    const url = String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+    if (/\.css(?:[?#]|$)/i.test(url)) return `<link rel="stylesheet" href="${url}" data-dg-expanded-asset>`;
+    if (/\.(?:m?js|cjs)(?:[?#]|$)/i.test(url)) return `<script src="${url}" data-dg-expanded-asset></script>`;
+    return `<link rel="preload" href="${url}" as="fetch" data-dg-expanded-asset>`;
+  }).join('');
+  const libraryJS = libraries.map(library => library.common_js || '').filter(Boolean).map((value, index) => `<script data-dg-expanded-library="${index}">${escapeScript(value)}</script>`).join('');
+  const combinedCSS = [libraryCSS, dependencyCSS, css].filter(Boolean).join('\n');
+  const style = combinedCSS ? `<style data-dg-expanded="${instance}">${combinedCSS}</style>` : '';
+  const propsJSON = JSON.stringify(props).replace(/</g, '\\u003c').replace(/<\/script/gi, '<\\/script');
+  const slotsJSON = JSON.stringify(slots).replace(/</g, '\\u003c').replace(/<\/script/gi, '<\\/script');
+  const slotExpression = `Object.fromEntries(Object.entries(${slotsJSON}).map(([name,html])=>[name,Array.from(document.createRange().createContextualFragment(html).childNodes)]))`;
+  const script = js ? `<script data-dg-expanded="${instance}">(()=>{const host=document.querySelector('[data-dg-instance="${instance}"]');const context={props:${propsJSON},slots:${slotExpression},App:window.App,component:${JSON.stringify({ name: component.full_name || `${component.library_slug}/${component.slug}`, revision: component.published_revision || 0 })}};${escapeScript(js)};if(typeof mount==='function')mount(host,context)})()</script>` : '';
+  const htmlSource = parse5.serialize(document);
+  return htmlSource.replace(/<\/head>/i, `${assetLinks}${style}</head>`).replace(/<\/body>/i, `${libraryJS}${script}</body>`);
+}
+
+async function expand(projectDir, flags) {
+  const pageID = flags.page;
+  const instance = flags.instance;
+  if (!pageID || !instance) throw new Error('Usage: draftgo components expand --page <id> --instance <data-dg-instance>');
+  const config = loadProjectConfig(projectDir);
+  const manifest = loadManifest(projectDir);
+  const entry = getEntry(manifest, 'pages', pageID);
+  if (!entry) throw new Error(`Page ${pageID} is not checked out; run draftgo checkout pages ${pageID} first.`);
+  const file = absolutePath(projectDir, entry.local_path);
+  const source = fs.readFileSync(file, 'utf8');
+  const parsed = parse5.parse(source);
+  const target = walk(parsed, node => node.attrs?.some(attr => attr.name === 'data-dg-instance' && attr.value === instance));
+  if (!target) throw new Error(`data-dg-instance not found: ${instance}`);
+  const use = target.attrs.find(attr => attr.name === 'data-dg-use')?.value;
+  if (!use) throw new Error('The selected instance does not have data-dg-use.');
+  const slug = use.split('/').pop();
+  const result = await request(config, 'GET', `components?q=${encodeURIComponent(slug)}&page_size=100`);
+  const component = (result.items || []).find(item => item.full_name === use || `${item.library_slug}/${item.slug}` === use || item.slug === slug);
+  if (!component) throw new Error(`Component not found: ${use}`);
+  let runtimeCatalog = null;
+  try {
+    runtimeCatalog = await request(config, 'POST', 'component-runtime/resolve', { components: [use] });
+  } catch {
+    // Older servers may not expose runtime resolve yet; the component can
+    // still be expanded with its own definition as a compatibility fallback.
+  }
+  fs.writeFileSync(file, expandHtml(source, instance, component, runtimeCatalog), 'utf8');
+  output({ page: String(pageID), instance, component: use, file: path.relative(projectDir, file).replace(/\\/g, '/') }, flags, 'Component expanded');
+  return 0;
+}
+
+module.exports = async function components(projectDir, positional = [], flags = {}) {
+  const action = String(positional[0] || 'search').toLowerCase();
+  if (action === 'libraries') return libraries(projectDir, positional.slice(1), flags);
+  if (action === 'list') return list(projectDir, flags);
+  if (action === 'search') return search(projectDir, positional.slice(1).join(' ').trim(), flags);
+  if (action === 'show') return show(projectDir, positional[1], flags);
+  if (action === 'create') return create(projectDir, flags);
+  if (action === 'delete') return remove(projectDir, positional[1], flags);
+  if (action === 'copy') return copy(projectDir, positional[1], flags);
+  if (action === 'checkout') return checkout(projectDir, positional[1], flags);
+  if (action === 'diff') return diff(projectDir, positional[1], flags);
+  if (action === 'verify') return verify(projectDir, positional[1], flags);
+  if (action === 'commit') return commit(projectDir, positional[1], flags);
+  if (action === 'publish') return publish(projectDir, positional[1], flags);
+  if (action === 'import') return importZIP(projectDir, positional[1], flags);
+  if (action === 'export') return exportZIP(projectDir, positional[1], flags);
+  if (action === 'expand') return expand(projectDir, flags);
+  throw new Error('Usage: draftgo components libraries|list|search|show|create|delete|copy|checkout|diff|verify|commit|publish|import|export|expand');
+};
+module.exports.expandHtml = expandHtml;
+module.exports.verifyDefinition = verifyDefinition;

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|custom-services> <id>');
     return 1;
   }
   const custom = require('./customService').isServiceType(resourceType);

package/src/commands/connect.js

@@ -19,11 +19,11 @@ async function promptServer(defaultValue) {
   }
 }
 
-async function promptToken() {
+async function promptAPIKey() {
   while (true) {
-    const value = String(await askPassword('DraftGo system access token (SAT)') || '').trim();
+    const value = String(await askPassword('DraftGo user API Key') || '').trim();
     if (value) return value;
-    log.dim('  A SAT is required.');
+    log.dim('  A DraftGo API Key is required.');
   }
 }
 
@@ -42,31 +42,41 @@ async function connect(projectDir, positional, flags = {}) {
     mcp_url: endpointConnection && endpointConnection.mcp_url || '',
   };
   const server = connection.server;
-  const token = flags.token ? String(flags.token).trim() : await promptToken();
+  const suppliedAPIKey = flags['api-key'] || flags.token;
+  const token = suppliedAPIKey ? String(suppliedAPIKey).trim() : await promptAPIKey();
   if (!token) {
-    log.err('A non-empty SAT is required.');
+    log.err('A non-empty DraftGo API Key is required.');
     return 1;
   }
   const timeoutMs = parseTimeout(flags.timeout);
+  if ((flags['scope-type'] === 'space') !== Boolean(flags['space-id'])) {
+    throw new Error('--scope-type space and --space-id must be provided together.');
+  }
 
-  log.step('Validating SAT and DraftGo MCP capabilities...');
+  log.step('Validating DraftGo API Key and MCP capabilities...');
   try {
     const diagnostic = await testConnection({ ...connection, server, token }, {
       timeoutMs,
+      scopeType: flags['scope-type'],
+      spaceId: flags['space-id'] && Number(flags['space-id']),
     });
     log.ok(`MCP ready (${diagnostic.tools.length} tools; tested ${diagnostic.testedCalls.join(', ')}).`);
   } catch (error) {
     const message = redactText(error && error.message ? error.message : error, [token]);
     if (!flags['allow-offline']) {
       log.err(message);
-      log.dim('  The project config was not changed. Run `draftgo mcp test` after checking the server and SAT.');
+      log.dim('  The project config was not changed. Run `draftgo mcp test` after checking the server and API Key.');
       return 1;
     }
     log.warn(`MCP validation unavailable: ${message}`);
     log.warn('Continuing only because --allow-offline was explicitly supplied.');
   }
 
-  const configFile = writeProjectConfig(projectDir, server, token, { mcp_url: connection.mcp_url });
+  const configFile = writeProjectConfig(projectDir, server, token, {
+    mcp_url: connection.mcp_url,
+    scope_type: flags['scope-type'],
+    space_id: flags['space-id'],
+  });
   log.ok(`Project configuration written: ${configFile}`);
 
   if (!flags['no-mcp-setup']) {