draftgo-cli 1.0.8 → 1.0.10

package/README.md

@@ -111,19 +111,19 @@ draftgo conflict resolve <type> <id>
 
 ```bash
 draftgo components search <query> --output json
-draftgo components show <library/component> --output json
+draftgo components show <id|library/component|query> --output json
 draftgo components expand --page <id> --instance <data-dg-instance>
 draftgo verify pages <id>
 
 # 开发组件：commit 保存草稿，publish 显式上线
-draftgo components checkout <library/component>
-draftgo components diff <library/component>
-draftgo components verify <library/component>
-draftgo components commit <library/component>
-draftgo components publish <library/component>
+draftgo components checkout <id|library/component>
+draftgo components diff <id|library/component>
+draftgo components verify <id|library/component>
+draftgo components commit <id|library/component>
+draftgo components publish <id|library/component>
 
 # 库管理和标准 ZIP 迁移
-draftgo components libraries list|show|create|update|delete
+draftgo components libraries list|search|show|create|update|delete
 draftgo components import <archive.zip> --dry-run
 draftgo components export <library> --file <archive.zip>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro, Pi, ZCode).",
   "bin": {
     "draftgo": "bin/draftgo.js"

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "entry": "SKILL.md",
   "description": "以 Skill/reference 任务路由、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",

package/src/cli.js

@@ -47,6 +47,9 @@ const VALUE_FLAGS = new Set([
   'description',
   'tags',
   'source-type',
+  'common-css',
+  'common-js',
+  'assets',
   'status',
   'module',
   'resource-type',

package/src/commands/components.js

@@ -9,6 +9,11 @@ const log = require('../logger');
 const { loadProjectConfig } = require('../projectConfig');
 const { loadManifest, getEntry, absolutePath } = require('../worktree/manifest');
 
+const COMPONENT_PAGE_SIZE = 100;
+const MAX_COMPONENT_PAGES = 1000;
+const DEFINITION_FIELDS = ['html', 'css', 'js', 'assets', 'props', 'slots', 'css_variables', 'events', 'dependencies', 'examples', 'usage', 'root_tag', 'meta'];
+const METADATA_FIELDS = ['name', 'slug', 'category', 'description', 'tags', 'status'];
+
 async function request(config, method, route, body) {
   const multipart = typeof FormData !== 'undefined' && body instanceof FormData;
   const response = await fetch(`${config.server}/api/${route.replace(/^\//, '')}`, {
@@ -25,14 +30,71 @@ 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 componentItems(result) {
+  if (Array.isArray(result)) return result;
+  return Array.isArray(result?.items) ? result.items : [];
+}
+
+async function listAllComponents(config, filters = {}) {
+  const items = [];
+  const seenPages = new Set();
+  for (let page = 1; page <= MAX_COMPONENT_PAGES; page += 1) {
+    const query = new URLSearchParams({ page: String(page), page_size: String(COMPONENT_PAGE_SIZE) });
+    for (const [key, value] of Object.entries(filters)) {
+      if (value !== undefined && value !== null && value !== '') query.set(key, String(value));
+    }
+    const result = await request(config, 'GET', `components?${query}`);
+    const pageItems = componentItems(result);
+    const signature = pageItems.map(item => String(item.id ?? componentName(item))).join('\u0000');
+    if (page > 1 && pageItems.length && seenPages.has(signature)) {
+      throw new Error(`DraftGo component catalog repeated page ${page}; refusing an incomplete result.`);
+    }
+    if (pageItems.length) seenPages.add(signature);
+    items.push(...pageItems);
+    const hasTotal = result?.total !== undefined && result?.total !== null
+      && Number.isFinite(Number(result.total)) && Number(result.total) >= 0;
+    if (hasTotal) {
+      if (items.length >= Number(result.total)) return items;
+      if (!pageItems.length) throw new Error(`DraftGo component catalog ended before its reported total on page ${page}.`);
+    } else if (pageItems.length < COMPONENT_PAGE_SIZE) return items;
+  }
+  throw new Error(`DraftGo component catalog exceeded ${MAX_COMPONENT_PAGES} pages.`);
+}
+
+function ambiguousComponent(selector, items) {
+  const candidates = items.map(item => `${componentName(item)} (id ${item.id})`).join(', ');
+  return new Error(`Component selector is ambiguous: ${selector}. Use an ID or full library/component name. Candidates: ${candidates}`);
+}
+
+async function findComponent(config, selector) {
+  const value = String(selector || '').trim();
+  if (!value) throw new Error('Component selector must be an ID or component name.');
+  if (/^[1-9]\d*$/.test(value)) {
+    try {
+      return await request(config, 'GET', `components/${value}`);
+    } catch (error) {
+      throw new Error(`Component not found: ${value}`, { cause: error });
+    }
+  }
+
+  if (value.includes('/')) {
+    const parts = value.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) throw new Error('Component name must be <library/component>.');
+    const [library, slug] = parts;
+    const items = await listAllComponents(config, { library, q: slug });
+    const exact = items.filter(item => componentName(item) === value
+      || (item.library_slug === library && item.slug === slug));
+    if (!exact.length) throw new Error(`Component not found: ${value}`);
+    if (exact.length > 1) throw ambiguousComponent(value, exact);
+    return request(config, 'GET', `components/${exact[0].id}`);
+  }
+
+  const items = await listAllComponents(config, { q: value });
+  const exact = items.filter(item => item.slug === value || item.name === value);
+  const candidates = exact.length ? exact : items;
+  if (!candidates.length) throw new Error(`Component not found: ${value}`);
+  if (candidates.length > 1) throw ambiguousComponent(value, candidates);
+  return request(config, 'GET', `components/${candidates[0].id}`);
 }
 
 function readJSON(projectDir, file) {
@@ -57,6 +119,21 @@ function definitionHash(definition) {
   return crypto.createHash('sha256').update(JSON.stringify(normalizeDefinition(definition))).digest('hex');
 }
 
+function metadataFrom(item = {}) {
+  return Object.fromEntries(METADATA_FIELDS.map(key => [key, key === 'tags' ? (item[key] || []) : (item[key] ?? '')]));
+}
+
+function changedFields(left, right, fields) {
+  return fields.filter(key => JSON.stringify(left?.[key] ?? null) !== JSON.stringify(right?.[key] ?? null));
+}
+
+function localChanges(definition, metadata, base) {
+  return [
+    ...changedFields(normalizeDefinition(definition), normalizeDefinition(base?.draft), DEFINITION_FIELDS),
+    ...changedFields(metadataFrom(metadata), metadataFrom(base), METADATA_FIELDS).map(key => `metadata.${key}`),
+  ];
+}
+
 function componentDir(projectDir, name) {
   const [library, slug] = String(name).split('/');
   if (!library || !slug || !/^[a-z0-9-]+$/.test(library) || !/^[a-z0-9-]+$/.test(slug)) {
@@ -80,20 +157,41 @@ function localDefinition(directory) {
   });
 }
 
-function writeComponentFiles(directory, item) {
+function atomicWriteFile(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const suffix = `${process.pid}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+  const temporary = `${file}.tmp-${suffix}`;
+  const backup = `${file}.bak-${suffix}`;
+  fs.writeFileSync(temporary, value);
+  let moved = false;
+  try {
+    if (fs.existsSync(file)) {
+      fs.renameSync(file, backup);
+      moved = true;
+    }
+    fs.renameSync(temporary, file);
+    if (moved) fs.rmSync(backup, { force: true });
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    if (moved && !fs.existsSync(file) && fs.existsSync(backup)) fs.renameSync(backup, file);
+    throw error;
+  }
+}
+
+function writeComponentFiles(directory, item, server) {
   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');
+  atomicWriteFile(path.join(directory, 'component.html'), item.draft.html || '');
+  atomicWriteFile(path.join(directory, 'component.css'), item.draft.css || '');
+  atomicWriteFile(path.join(directory, 'component.js'), item.draft.js || '');
   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,
+    version: item.version, remote_draft_hash: definitionHash(item.draft), updated_at: item.updated_at,
     ...contractFrom(item.draft),
   };
-  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');
+  atomicWriteFile(path.join(directory, 'component.json'), `${JSON.stringify(metadata, null, 2)}\n`);
+  atomicWriteFile(path.join(directory, '.base.json'), `${JSON.stringify({ ...item, server }, null, 2)}\n`);
 }
 
 function output(value, flags, title) {
@@ -105,67 +203,125 @@ function output(value, flags, title) {
 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}`);
+  let items;
+  if (/^[1-9]\d*$/.test(query) || query.includes('/')) {
+    items = [await findComponent(config, query)];
+  } else {
+    items = await listAllComponents(config, { q: query });
+  }
+  output(items, flags, `DraftGo components: ${query}`);
   return 0;
 }
 
-async function show(projectDir, name, flags) {
-  if (!name) throw new Error('Usage: draftgo components show <library/component>');
+async function show(projectDir, selector, flags) {
+  if (!selector) throw new Error('Usage: draftgo components show <id|library/component|query>');
   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}`);
+  const item = await findComponent(config, selector);
+  output(item, flags, `DraftGo component ${componentName(item)}`);
   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');
+  const items = await listAllComponents(config, { library: flags.library, status: flags.status, category: flags.category });
+  output(items, flags, 'DraftGo components');
   return 0;
 }
 
+async function listAllLibraries(config, filters = {}) {
+  const items = [];
+  const seenPages = new Set();
+  for (let page = 1; page <= MAX_COMPONENT_PAGES; page += 1) {
+    const query = new URLSearchParams({ page: String(page), page_size: String(COMPONENT_PAGE_SIZE) });
+    for (const [key, value] of Object.entries(filters)) {
+      if (value !== undefined && value !== null && value !== '') query.set(key, String(value));
+    }
+    const result = await request(config, 'GET', `component-libraries?${query}`);
+    const pageItems = componentItems(result);
+    const signature = pageItems.map(item => String(item.id ?? item.slug)).join('\u0000');
+    if (page > 1 && pageItems.length && seenPages.has(signature)) {
+      throw new Error(`DraftGo component library catalog repeated page ${page}; refusing an incomplete result.`);
+    }
+    if (pageItems.length) seenPages.add(signature);
+    items.push(...pageItems);
+    const hasTotal = result?.total !== undefined && result?.total !== null
+      && Number.isFinite(Number(result.total)) && Number(result.total) >= 0;
+    if (hasTotal) {
+      if (items.length >= Number(result.total)) return items;
+      if (!pageItems.length) throw new Error(`DraftGo component library catalog ended before its reported total on page ${page}.`);
+    } else if (pageItems.length < COMPONENT_PAGE_SIZE) return items;
+  }
+  throw new Error(`DraftGo component library catalog exceeded ${MAX_COMPONENT_PAGES} pages.`);
+}
+
+function ambiguousLibrary(selector, items) {
+  const candidates = items.map(item => `${item.slug} (${item.name}, id ${item.id})`).join(', ');
+  return new Error(`Component library selector is ambiguous: ${selector}. Use an ID or exact slug. Candidates: ${candidates}`);
+}
+
+async function findLibrary(config, selector) {
+  const value = String(selector || '').trim();
+  if (!value) throw new Error('Component library selector must be an ID, slug, or name.');
+  if (/^[1-9]\d*$/.test(value)) {
+    try { return await request(config, 'GET', `component-libraries/${value}`); } catch (error) {
+      throw new Error(`Component library not found: ${value}`, { cause: error });
+    }
+  }
+  const items = await listAllLibraries(config, { q: value });
+  const slugMatches = items.filter(item => item.slug === value);
+  if (slugMatches.length === 1) return request(config, 'GET', `component-libraries/${slugMatches[0].id}`);
+  if (slugMatches.length > 1) throw ambiguousLibrary(value, slugMatches);
+  const nameMatches = items.filter(item => item.name === value);
+  const candidates = nameMatches.length ? nameMatches : items;
+  if (!candidates.length) throw new Error(`Component library not found: ${value}`);
+  if (candidates.length > 1) throw ambiguousLibrary(value, candidates);
+  return request(config, 'GET', `component-libraries/${candidates[0].id}`);
+}
+
 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 === 'list') { output(await listAllLibraries(config, { status: flags.status }), flags, 'DraftGo component libraries'); return 0; }
+  if (action === 'search') {
+    const query = positional.slice(1).join(' ').trim();
+    if (!query) throw new Error('Usage: draftgo components libraries search <query>');
+    output(await listAllLibraries(config, { q: query, status: flags.status }), flags, `DraftGo component libraries: ${query}`);
+    return 0;
+  }
+  if (action === 'show') {
+    const item = await findLibrary(config, positional[1]);
+    output(item, flags, `Component library ${item.slug}`);
+    return 0;
+  }
   if (action === 'delete') {
-    const item = await find(positional[1]);
+    const item = await findLibrary(config, 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) };
+    const current = action === 'update' ? await findLibrary(config, positional[1]) : {};
+    const source = { ...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];
+      if (flags[flag] !== undefined) source[key] = flags[flag];
     }
+    if (flags['common-css'] !== undefined) source.common_css = flags['common-css'];
+    if (flags['common-js'] !== undefined) source.common_js = flags['common-js'];
+    if (flags.assets !== undefined) source.assets = csv(flags.assets) || [];
+    const input = Object.fromEntries(['name', 'slug', 'description', 'source_type', 'common_css', 'common_js', 'assets', 'status']
+      .map(key => [key, source[key] ?? (key === 'assets' ? [] : '')]));
+    if (action === 'update') input.expected_version = current.version;
     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');
+  throw new Error('Usage: draftgo components libraries list|search|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]');
+  if (!flags.library) throw new Error('Usage: draftgo components create --library <id|slug> --name <name> --slug <slug> [--file input.json]');
+  const library = await findLibrary(config, flags.library);
   const fileInput = readJSON(projectDir, flags.file);
   const input = {
     ...fileInput, library_id: library.id,
@@ -190,9 +346,8 @@ async function remove(projectDir, name, flags) {
 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]');
+  if (!flags.slug) throw new Error('Usage: draftgo components copy <id|library/component> --slug <new-slug> [--library id|slug] [--name name]');
+  const library = await findLibrary(config, flags.library || item.library_slug);
   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,
@@ -207,11 +362,12 @@ async function checkout(projectDir, name, flags) {
   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)) {
+    const metadata = JSON.parse(fs.readFileSync(path.join(directory, 'component.json'), 'utf8'));
+    if (localChanges(localDefinition(directory), metadata, base).length) {
       throw new Error(`Local changes present for ${name}; commit them or use --force.`);
     }
   }
-  writeComponentFiles(directory, item);
+  writeComponentFiles(directory, item, config.server);
   output({ component: componentName(item), directory: path.relative(projectDir, directory).replace(/\\/g, '/') }, flags, 'Component checked out');
   return 0;
 }
@@ -227,24 +383,46 @@ function localState(projectDir, name) {
   };
 }
 
+function assertLocalState(state, remote, config) {
+  if (state.base.server && String(state.base.server).replace(/\/$/, '') !== String(config.server).replace(/\/$/, '')) {
+    throw new Error(`Component checkout belongs to ${state.base.server}; checkout again before using ${config.server}.`);
+  }
+  for (const key of ['id', 'library_id', 'library_slug', 'slug']) {
+    if (String(state.metadata[key] ?? '') !== String(state.base[key] ?? '')) {
+      throw new Error(`component.json cannot change component identity field ${key}; create or copy a component instead.`);
+    }
+  }
+  if (String(remote.id) !== String(state.base.id)) throw new Error('Local component base does not match the selected remote component.');
+}
+
+async function selectedState(projectDir, config, selector) {
+  const remote = await findComponent(config, selector);
+  const name = componentName(remote);
+  const state = localState(projectDir, name);
+  assertLocalState(state, remote, config);
+  return { remote, name, state };
+}
+
 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', 'assets', '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 selected = await selectedState(projectDir, config, name);
+  const { state, remote } = selected;
+  const changed = (left, right) => changedFields(normalizeDefinition(left), normalizeDefinition(right), DEFINITION_FIELDS);
   const result = {
-    component: name, local_vs_base: changed(state.definition, state.base.draft),
-    local_vs_remote_draft: changed(state.definition, remote.draft),
+    component: selected.name,
+    local_vs_base: localChanges(state.definition, state.metadata, state.base),
+    local_vs_remote_draft: [
+      ...changed(state.definition, remote.draft),
+      ...changedFields(metadataFrom(state.metadata), metadataFrom(remote), METADATA_FIELDS).map(key => `metadata.${key}`),
+    ],
     local_vs_published: changed(state.definition, remote.published),
-    base_remote_changed: definitionHash(state.base.draft) !== definitionHash(remote.draft),
+    base_remote_changed: state.base.version !== remote.version
+      || localChanges(remote.draft, remote, state.base).length > 0,
+    base_version: state.base.version,
+    remote_version: remote.version,
     published_revision: remote.published_revision || 0,
   };
-  output(result, flags, `Component diff ${name}`);
+  output(result, flags, `Component diff ${selected.name}`);
   return 0;
 }
 
@@ -271,54 +449,64 @@ function verifyDefinition(definition) {
 
 async function verify(projectDir, name, flags) {
   const config = loadProjectConfig(projectDir);
-  const state = localState(projectDir, name);
+  const selected = await selectedState(projectDir, config, name);
+  const { state } = selected;
   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}`);
+  const result = { component: selected.name, valid: errors.length === 0, errors };
+  output(result, flags, `Component verify ${selected.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 selected = await selectedState(projectDir, config, name);
+  const { state, remote } = selected;
   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');
+  if (!Number.isInteger(remote.version) || remote.version < 1 || !Number.isInteger(state.base.version) || state.base.version < 1) {
+    throw new Error(`Component ${selected.name} is missing a valid version; run components checkout again.`);
+  }
+  if (remote.version !== state.base.version || localChanges(remote.draft, remote, state.base).length) {
+    throw new Error(`Remote component changed after checkout for ${selected.name}; run components checkout after preserving local changes.`);
+  }
+  if (!localChanges(state.definition, state.metadata, remote).length) {
+    writeComponentFiles(state.directory, remote, config.server);
+    output({ component: selected.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,
+    expected_version: remote.version,
   });
-  writeComponentFiles(state.directory, result);
+  writeComponentFiles(state.directory, result, config.server);
   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)) {
+  const selected = await selectedState(projectDir, config, name);
+  const { state, remote } = selected;
+  if (!Number.isInteger(remote.version) || remote.version < 1 || !Number.isInteger(state.base.version) || state.base.version < 1) {
+    throw new Error(`Component ${selected.name} is missing a valid version; run components checkout again.`);
+  }
+  if (remote.version !== state.base.version || localChanges(remote.draft, remote, state.base).length) {
+    throw new Error(`Remote component changed after checkout for ${selected.name}; checkout again before publish.`);
+  }
+  if (localChanges(state.definition, state.metadata, remote).length) {
     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);
+  const result = await request(config, 'POST', `components/${remote.id}/publish`, { expected_version: remote.version });
+  writeComponentFiles(state.directory, result, config.server);
   output(result, flags, 'Component published');
   return 0;
 }
@@ -337,15 +525,8 @@ async function importZIP(projectDir, file, flags) {
 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 library = await findLibrary(config, librarySlug);
+  const components = await listAllComponents(config, { library: library.slug });
   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 },
@@ -482,7 +663,10 @@ function expandHtml(source, instance, component, runtimeCatalog = null) {
     .map(item => item.definition?.css || '')
     .filter(Boolean)
     .join('\n');
-  const assets = libraries.flatMap(library => library.assets || []).filter(Boolean);
+  const assets = [...new Set([
+    ...libraries.flatMap(library => library.assets || []),
+    ...(runtimeCatalog?.components || []).flatMap(item => item.definition?.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>`;
@@ -490,6 +674,10 @@ function expandHtml(source, instance, component, runtimeCatalog = null) {
     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('');
+  // Component JS is a host-scoped mount function in the Page runtime, not a
+  // registration script. Dependency definitions without a concrete expanded
+  // host must not be executed globally; their CSS and external assets are the
+  // dependency-level resources that apply to this expanded instance.
   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');
@@ -515,18 +703,31 @@ async function expand(projectDir, flags) {
   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.
+  const remote = await findComponent(config, use);
+  if (componentName(remote) !== use) throw new Error(`Component reference did not resolve exactly: ${use}`);
+  const runtimeCatalog = await request(config, 'POST', 'component-runtime/resolve', { components: [use] });
+  if (!runtimeCatalog || !Array.isArray(runtimeCatalog.components) || !Array.isArray(runtimeCatalog.libraries)) {
+    throw new Error(`DraftGo runtime returned an incomplete component catalog for ${use}.`);
+  }
+  if (Array.isArray(runtimeCatalog.missing) && runtimeCatalog.missing.length) {
+    throw new Error(`Unable to expand ${use}; missing runtime dependencies: ${runtimeCatalog.missing.join(', ')}`);
+  }
+  const byName = new Map(runtimeCatalog.components.map(item => [item.name, item]));
+  const runtimeComponent = byName.get(use);
+  if (!runtimeComponent?.definition) throw new Error(`DraftGo runtime did not return the exact published component ${use}.`);
+  for (const item of runtimeCatalog.components) {
+    for (const dependency of item.definition?.dependencies || []) {
+      if (!byName.has(dependency)) throw new Error(`Unable to expand ${use}; runtime dependency is missing: ${dependency}`);
+    }
+  }
+  const librarySlugs = new Set(runtimeCatalog.libraries.map(item => item.slug));
+  for (const item of runtimeCatalog.components) {
+    const library = String(item.name || '').split('/')[0];
+    if (!library || !librarySlugs.has(library)) throw new Error(`Unable to expand ${use}; runtime library is missing: ${library || '(unknown)'}`);
   }
-  fs.writeFileSync(file, expandHtml(source, instance, component, runtimeCatalog), 'utf8');
+  const component = { ...remote, published: runtimeComponent.definition, published_revision: runtimeComponent.revision };
+  const expanded = expandHtml(source, instance, component, runtimeCatalog);
+  atomicWriteFile(file, expanded);
   output({ page: String(pageID), instance, component: use, file: path.relative(projectDir, file).replace(/\\/g, '/') }, flags, 'Component expanded');
   return 0;
 }

package/src/commands/help.js

@@ -54,15 +54,15 @@ Usage:
                                     --stat/--summary omit the full patch.
   draftgo commit <type> <id...>    Validate and upload complete checked-out bodies/files.
   draftgo components search <query>  Search the live component catalog.
-  draftgo components show <library/component>
+  draftgo components show <id|library/component|query>
                                     Show HTML, props, slots, CSS variables and revision.
   draftgo components expand --page <id> --instance <data-dg-instance>
                                     Expand one component in a checked-out Page worktree.
-  draftgo components libraries list|show|create|update|delete
-                                    Manage component libraries.
+  draftgo components libraries list|search|show|create|update|delete
+                                    Manage component libraries.
   draftgo components list|create|copy|delete
                                     Manage component catalog entries.
-  draftgo components checkout|diff|verify|commit|publish <library/component>
+  draftgo components checkout|diff|verify|commit|publish <id|library/component>
                                     Develop a component draft locally, then publish explicitly.
   draftgo components import <zip> [--dry-run]
   draftgo components export <library> [--file <zip>]