draftgo-cli 3.0.35 → 3.0.38

package/src/worktree/streams.js

@@ -0,0 +1,200 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { once } = require('events');
+const { WorktreeError } = require('./errors');
+
+function normalizeSha256(value) {
+  if (value == null || value === '') return null;
+  const normalized = String(value).trim().toLowerCase().replace(/^sha-?256[:=]/, '');
+  return /^[a-f0-9]{64}$/.test(normalized) ? normalized : null;
+}
+
+function tempPathFor(destination) {
+  const suffix = crypto.randomBytes(8).toString('hex');
+  return path.join(
+    path.dirname(destination),
+    `.${path.basename(destination)}.${process.pid}.${suffix}.tmp`
+  );
+}
+
+async function ensureParent(filePath) {
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+}
+
+async function syncDirectory(directory) {
+  let handle;
+  try {
+    handle = await fs.promises.open(directory, 'r');
+    await handle.sync();
+  } catch {
+    // Directory fsync is unavailable on some Windows filesystems.
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+}
+
+function bodyIterable(body) {
+  if (!body) throw new WorktreeError('DOWNLOAD_INCOMPLETE', 'The content response did not include a body.');
+  if (typeof body[Symbol.asyncIterator] === 'function') return body;
+  if (typeof body.getReader === 'function') {
+    return {
+      async *[Symbol.asyncIterator]() {
+        const reader = body.getReader();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) return;
+            yield value;
+          }
+        } finally {
+          reader.releaseLock();
+        }
+      },
+    };
+  }
+  throw new WorktreeError('DOWNLOAD_INCOMPLETE', 'The content response body is not streamable.');
+}
+
+async function writeChunk(stream, chunk) {
+  if (stream.write(chunk)) return;
+  await once(stream, 'drain');
+}
+
+async function closeStream(stream) {
+  stream.end();
+  await once(stream, 'close');
+}
+
+async function streamToFiles(body, destinations, options = {}) {
+  const unique = [...new Set(destinations.map((item) => path.resolve(item)))];
+  if (!unique.length) throw new WorktreeError('INVALID_DESTINATION', 'At least one destination is required.');
+  await Promise.all(unique.map(ensureParent));
+
+  const temporaries = unique.map((destination) => ({
+    destination,
+    temporary: tempPathFor(destination),
+    backup: `${tempPathFor(destination)}.bak`,
+    stream: null,
+    backedUp: false,
+    installed: false,
+  }));
+  const hash = crypto.createHash('sha256');
+  let size = 0;
+  let complete = false;
+
+  try {
+    for (const item of temporaries) {
+      item.stream = fs.createWriteStream(item.temporary, { flags: 'wx', mode: 0o600 });
+      await once(item.stream, 'open');
+    }
+
+    for await (const rawChunk of bodyIterable(body)) {
+      const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+      hash.update(chunk);
+      size += chunk.length;
+      for (const item of temporaries) await writeChunk(item.stream, chunk);
+    }
+
+    for (const item of temporaries) {
+      await new Promise((resolve, reject) => item.stream.end((error) => error ? reject(error) : resolve()));
+      await fs.promises.open(item.temporary, 'r+').then(async (handle) => {
+        try { await handle.sync(); } finally { await handle.close(); }
+      });
+    }
+
+    const actualHash = hash.digest('hex');
+    const expectedHash = normalizeSha256(options.expectedHash);
+    if (options.expectedHash && !expectedHash) {
+      throw new WorktreeError('INVALID_CONTENT_HASH', 'The backend returned an invalid SHA-256 hash.');
+    }
+    if (expectedHash && actualHash !== expectedHash) {
+      throw new WorktreeError('HASH_MISMATCH', 'Downloaded content did not match its SHA-256 metadata.', {
+        expected_hash: expectedHash,
+        actual_hash: actualHash,
+      });
+    }
+    if (options.expectedSize != null && Number(options.expectedSize) !== size) {
+      throw new WorktreeError('DOWNLOAD_INCOMPLETE', 'Downloaded content size did not match its metadata.', {
+        expected_size: Number(options.expectedSize),
+        actual_size: size,
+      });
+    }
+
+    try {
+      for (const item of temporaries) {
+        if (fs.existsSync(item.destination)) {
+          await fs.promises.rename(item.destination, item.backup);
+          item.backedUp = true;
+        }
+      }
+      for (const item of temporaries) {
+        await fs.promises.rename(item.temporary, item.destination);
+        item.installed = true;
+      }
+    } catch (error) {
+      for (const item of [...temporaries].reverse()) {
+        if (item.installed) await fs.promises.rm(item.destination, { force: true }).catch(() => {});
+        if (item.backedUp) await fs.promises.rename(item.backup, item.destination).catch(() => {});
+      }
+      throw error;
+    }
+    await Promise.all([...new Set(unique.map(path.dirname))].map(syncDirectory));
+    await Promise.all(temporaries.map((item) => fs.promises.rm(item.backup, { force: true })));
+    complete = true;
+    return { hash: actualHash, size };
+  } finally {
+    for (const item of temporaries) {
+      if (item.stream && !item.stream.closed) item.stream.destroy();
+      if (!complete) await fs.promises.rm(item.temporary, { force: true }).catch(() => {});
+      if (!complete && item.backedUp && fs.existsSync(item.backup) && !fs.existsSync(item.destination)) {
+        await fs.promises.rename(item.backup, item.destination).catch(() => {});
+      }
+      if (complete) await fs.promises.rm(item.backup, { force: true }).catch(() => {});
+    }
+  }
+}
+
+async function hashFile(filePath) {
+  const hash = crypto.createHash('sha256');
+  let size = 0;
+  const stream = fs.createReadStream(filePath);
+  for await (const chunk of stream) {
+    hash.update(chunk);
+    size += chunk.length;
+  }
+  return { hash: hash.digest('hex'), size };
+}
+
+async function copyFileAtomic(source, destination, options = {}) {
+  return streamToFiles(fs.createReadStream(source), [destination], options);
+}
+
+async function writeJsonAtomic(destination, value) {
+  await ensureParent(destination);
+  const temporary = tempPathFor(destination);
+  let handle;
+  try {
+    handle = await fs.promises.open(temporary, 'wx', 0o600);
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await fs.promises.rename(temporary, destination);
+    await syncDirectory(path.dirname(destination));
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+    await fs.promises.rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+module.exports = {
+  normalizeSha256,
+  tempPathFor,
+  streamToFiles,
+  hashFile,
+  copyFileAtomic,
+  writeJsonAtomic,
+};

package/src/worktree/types.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const crypto = require('crypto');
+const { WorktreeError } = require('./errors');
+
+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' }),
+});
+
+const TYPE_ALIASES = new Map([
+  ['page', 'pages'],
+  ['pages', 'pages'],
+  ['nav', 'navigations'],
+  ['navigation', 'navigations'],
+  ['navigations', 'navigations'],
+  ['doc', 'docs'],
+  ['docs', 'docs'],
+  ['article', 'docs'],
+  ['articles', 'docs'],
+  ['docs/articles', 'docs'],
+]);
+
+const CONTENT_EXTENSIONS = new Map([
+  ['text/html', '.html'],
+  ['application/xhtml+xml', '.html'],
+  ['text/markdown', '.md'],
+  ['text/x-markdown', '.md'],
+  ['text/plain', '.txt'],
+]);
+
+function canonicalResourceType(value) {
+  const key = String(value || '').trim().toLowerCase().replace(/\\/g, '/');
+  const canonical = TYPE_ALIASES.get(key);
+  if (!canonical) {
+    throw new WorktreeError(
+      'UNSUPPORTED_RESOURCE_TYPE',
+      `Unsupported checkout resource type: ${value}. Expected pages, nav, or docs.`,
+      { resource_type: value }
+    );
+  }
+  return canonical;
+}
+
+function mediaType(contentType) {
+  return String(contentType || '').split(';', 1)[0].trim().toLowerCase();
+}
+
+function normalizeExtension(contentType, backendExtension) {
+  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();
+}
+
+function safeIdSegment(value) {
+  const raw = String(value == null ? '' : value).trim();
+  if (!raw) throw new WorktreeError('INVALID_RESOURCE_ID', 'A non-empty resource id is required.');
+  let clean = raw.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^\.+/, '').slice(0, 80);
+  if (!clean) clean = 'resource';
+  if (clean !== raw) {
+    const suffix = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 10);
+    clean = `${clean.slice(0, 68)}-${suffix}`;
+  }
+  return clean;
+}
+
+function entryKey(resourceType, resourceId) {
+  return `${canonicalResourceType(resourceType)}:${String(resourceId)}`;
+}
+
+function resourceFileName(resourceType, resourceId, extension) {
+  const canonical = canonicalResourceType(resourceType);
+  return `${RESOURCE_TYPES[canonical].prefix}_${safeIdSegment(resourceId)}${extension}`;
+}
+
+module.exports = {
+  RESOURCE_TYPES,
+  TYPE_ALIASES,
+  CONTENT_EXTENSIONS,
+  canonicalResourceType,
+  mediaType,
+  normalizeExtension,
+  safeIdSegment,
+  entryKey,
+  resourceFileName,
+};

package/src/worktree/validate.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const fs = require('fs');
+const parse5 = require('parse5');
+const { WorktreeError } = require('./errors');
+const { mediaType } = require('./types');
+
+function validateContentFile(filePath, contentType) {
+  if (!fs.existsSync(filePath)) {
+    throw new WorktreeError('LOCAL_CONTENT_MISSING', `Checked-out content is missing: ${filePath}`);
+  }
+  if (!['text/html', 'application/xhtml+xml'].includes(mediaType(contentType))) return [];
+  const charsetMatch = String(contentType || '').match(/;\s*charset\s*=\s*[']?([^;'\s]+)/i);
+  const charset = charsetMatch ? charsetMatch[1] : 'utf-8';
+  let source;
+  try {
+    source = new TextDecoder(charset, { fatal: true }).decode(fs.readFileSync(filePath));
+  } catch (error) {
+    throw new WorktreeError('LOCAL_CONTENT_ENCODING_INVALID',
+      `Unable to validate HTML using charset ${charset}: ${error.message}`);
+  }
+  const errors = [];
+  parse5.parse(source, {
+    onParseError(error) {
+      if (error.code === 'missing-doctype') return;
+      errors.push({ code: error.code, line: error.startLine || null, column: error.startCol || null });
+    },
+  });
+  if (errors.length) {
+    throw new WorktreeError('LOCAL_CONTENT_INVALID', 'HTML structure check failed before commit.', {
+      errors: errors.slice(0, 20),
+    });
+  }
+  return errors;
+}
+
+module.exports = { validateContentFile };

package/resources/skill/pull/SKILL.md

@@ -1,33 +0,0 @@
----
-name: draftgo-pull
-description: Pull all or selected DraftGo resources from the connected server into local .draftgo indexes and referenced files before inspection or modification.
----
-
-# DraftGo 拉取
-
-使用 `draftgo pull`；内部 Python 脚本由 CLI 定位和执行。
-
-## 命令
-
-```bash
-draftgo pull
-draftgo pull <type> [id...]
-```
-
-不带参数时拉取全部资源。支持的类型：
-
-`pages`、`nav`、`db_meta`、`aihub`、`system_config`、`docs`、`doc_categories`、`custom_scripts`、`roles`、`users`。
-
-## 执行
-
-1. 在本地资源缺失、过期、损坏，或用户明确要求同步云端版本时运行 pull。
-2. 只拉取当前工作需要的类型或 id；需要建立完整项目上下文时运行无参数的 `draftgo pull`。
-3. 拉取后重新读取对应 `index.json` 以及其中 `html_file`、`content_file`、`code_file` 指向的文件。
-4. 修改自定义服务前，确认 `code_file`、`go_mod`、`go_sum` 已同步，并读取 `../references/custom-services.md`。
-5. 运行 `draftgo map` 确认跨资源入口或依赖已更新。
-
-## 失败处理
-
-- 缺少 `.draftgo/config.json`：运行 `draftgo connect`。
-- HTTP 401：连接令牌无效，重新运行 `draftgo connect`。
-- 返回空列表但预期存在资源：检查令牌是否具备对应读取权限，不把空结果直接当成资源不存在。