skillcaddy 0.27.0

package/lib/skillMetadata.js

@@ -0,0 +1,191 @@
+import { constants } from 'node:fs';
+import { access, lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { requirePath } from './projectPath.js';
+import { normalizeRoots } from './roots.js';
+import {
+  assertInsideAllowedSkillSources,
+  resolveAllowedSkillSource
+} from './sourcePolicy.js';
+
+const METADATA_FILE = 'skillcaddy.json';
+const METADATA_ROOT = '.skillcaddy/metadata';
+const MAX_TAGS = 12;
+const MAX_TAG_LENGTH = 40;
+const MAX_NOTE_LENGTH = 500;
+
+export async function readSkillMetadata(roots, skillPath) {
+  const sidecarMetadataPath = getSidecarMetadataPath(roots, skillPath);
+  try {
+    const content = await readFile(sidecarMetadataPath, 'utf8');
+    return {
+      ...normalizeMetadata(JSON.parse(content)),
+      metadataPath: sidecarMetadataPath,
+      hasMetadata: true,
+      metadataStorage: 'sidecar'
+    };
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      return {
+        ...emptyMetadata(sidecarMetadataPath),
+        metadataError: `skillcaddy.json 读取失败：${error.message}`
+      };
+    }
+  }
+
+  return emptyMetadata(sidecarMetadataPath);
+}
+
+export async function updateSkillMetadata(roots, input) {
+  const resolvedRoots = normalizeRoots(roots);
+  const skillPath = path.resolve(requirePath(input.skillPath, 'skillPath'));
+  assertInsideAllowedSkillSources(resolvedRoots, skillPath);
+  await assertDirectory(skillPath, 'skillPath');
+
+  const metadata = normalizeMetadata(input);
+  const metadataPath = getSidecarMetadataPath(resolvedRoots, skillPath);
+  await mkdir(path.dirname(metadataPath), { recursive: true });
+  await writeFile(metadataPath, `${JSON.stringify({ note: metadata.note, tags: metadata.tags, autoEnable: metadata.autoEnable }, null, 2)}\n`, { encoding: 'utf8', flag: input.createOnly ? 'wx' : 'w' });
+
+  return {
+    ok: true,
+    skillPath,
+    metadataPath,
+    metadata: {
+      ...metadata,
+      metadataPath,
+      hasMetadata: true,
+      metadataStorage: 'sidecar'
+    }
+  };
+}
+
+export async function migrateLegacySkillMetadata(roots, skills, options = {}) {
+  const inspected = await Promise.all(skills.map(async (skill) => {
+    if (skill.hasMetadata || skill.metadataError) return null;
+
+    const legacyPath = getLegacyMetadataPath(skill.path);
+    try {
+      const metadata = normalizeMetadata(JSON.parse(await readFile(legacyPath, 'utf8')));
+      return {
+        item: {
+          id: skill.id,
+          skillPath: skill.path,
+          legacyPath,
+          sidecarPath: getSidecarMetadataPath(roots, skill.path)
+        },
+        metadata
+      };
+    } catch (error) {
+      if (error.code === 'ENOENT') return null;
+      return {
+        invalid: {
+          id: skill.id,
+          metadataError: `legacy skillcaddy.json 读取失败：${error.message}`
+        }
+      };
+    }
+  }));
+
+  const candidates = inspected.filter((entry) => entry?.item);
+  const pending = candidates.map((entry) => entry.item);
+  const invalid = inspected.filter((entry) => entry?.invalid).map((entry) => entry.invalid);
+
+  if (!options.write) {
+    return { dryRun: true, pending, migrated: 0, invalid };
+  }
+
+  for (const candidate of candidates) {
+    await updateSkillMetadata(roots, {
+      skillPath: candidate.item.skillPath,
+      ...candidate.metadata
+    });
+  }
+
+  return { dryRun: false, pending, migrated: pending.length, invalid };
+}
+
+function getLegacyMetadataPath(skillPath) {
+  return path.join(skillPath, METADATA_FILE);
+}
+
+/**
+ * sidecar 元数据属于原件库：它随 library image 一起搬运（ADR-0011），
+ * 因此即使 skill 本身来自代码根的仓库 skills 桶，元数据也写在原件库根下。
+ */
+function getSidecarMetadataPath(roots, skillPath) {
+  const { libraryRoot } = normalizeRoots(roots);
+  const source = resolveAllowedSkillSource(roots, skillPath);
+  if (!source) {
+    throw new Error(`skill 不在允许的来源目录内：${skillPath}`);
+  }
+  return path.join(libraryRoot, METADATA_ROOT, source.sourceFolder, source.relativePath, METADATA_FILE);
+}
+
+function normalizeMetadata(input = {}) {
+  return {
+    note: normalizeNote(input.note),
+    tags: normalizeTags(input.tags),
+    autoEnable: normalizeAutoEnable(input.autoEnable)
+  };
+}
+
+function normalizeNote(value) {
+  if (value === undefined || value === null) return '';
+  if (typeof value !== 'string') throw new Error('note 必须是字符串');
+  const note = value.trim();
+  if (note.length > MAX_NOTE_LENGTH) {
+    throw new Error(`note 不能超过 ${MAX_NOTE_LENGTH} 个字符`);
+  }
+  return note;
+}
+
+function normalizeTags(value) {
+  if (value === undefined || value === null || value === '') return [];
+  const tags = Array.isArray(value) ? value : String(value).split(',');
+  const normalized = [];
+
+  for (const tag of tags) {
+    if (typeof tag !== 'string') throw new Error('tags 只能包含字符串');
+    const value = tag.trim();
+    if (!value) continue;
+    if (value.length > MAX_TAG_LENGTH) {
+      throw new Error(`tag 不能超过 ${MAX_TAG_LENGTH} 个字符：${value}`);
+    }
+    if (!normalized.includes(value)) normalized.push(value);
+    if (normalized.length > MAX_TAGS) {
+      throw new Error(`tags 不能超过 ${MAX_TAGS} 个`);
+    }
+  }
+
+  return normalized;
+}
+
+function normalizeAutoEnable(value) {
+  if (value === undefined || value === null || value === '') return true;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(normalized)) return true;
+    if (['false', '0', 'no', 'off'].includes(normalized)) return false;
+  }
+  throw new Error('autoEnable 必须是布尔值');
+}
+
+function emptyMetadata(metadataPath) {
+  return {
+    note: '',
+    tags: [],
+    autoEnable: true,
+    metadataPath,
+    hasMetadata: false
+  };
+}
+
+async function assertDirectory(targetPath, label) {
+  await access(targetPath, constants.F_OK);
+  const stat = await lstat(targetPath);
+  if (!stat.isDirectory()) {
+    throw new Error(`${label} 必须是目录：${targetPath}`);
+  }
+}