agentfold 0.1.0

package/lib/scope.mjs

@@ -0,0 +1,158 @@
+import path from 'node:path';
+import { pathExists, readJson } from './util.mjs';
+
+const SELECTABLE_TYPES = ['skills', 'prompts', 'rules', 'commands', 'mcp', 'subagents'];
+
+function asStringArray(value) {
+  if (!value) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === 'string');
+  }
+
+  return typeof value === 'string' ? [value] : [];
+}
+
+function toKebabCase(input) {
+  return String(input || '')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/_/g, '-')
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+async function readTagArray(tagsPath) {
+  const tags = await readJson(tagsPath);
+  if (!Array.isArray(tags)) {
+    throw new Error(`Expected array of tags at ${tagsPath}`);
+  }
+
+  return tags
+    .map((value) => toKebabCase(value))
+    .filter(Boolean);
+}
+
+export async function loadScopeTagEnum({ configRoot }) {
+  const tagsPath = path.join(configRoot, 'config', 'definitions', 'scope-tags.json');
+
+  if (!(await pathExists(tagsPath))) {
+    return [];
+  }
+
+  const tags = await readTagArray(tagsPath);
+  return [...new Set(tags)].sort((a, b) => a.localeCompare(b));
+}
+
+function normalizeTagSelector(rawTags) {
+  if (Array.isArray(rawTags)) {
+    return {
+      mode: 'any',
+      values: rawTags.map((value) => toKebabCase(value)).filter(Boolean),
+    };
+  }
+
+  if (!rawTags || typeof rawTags !== 'object') {
+    return { mode: 'any', values: [] };
+  }
+
+  const mode = rawTags.mode === 'all' ? 'all' : 'any';
+  const values = asStringArray(rawTags.values)
+    .map((value) => toKebabCase(value))
+    .filter(Boolean);
+
+  return { mode, values };
+}
+
+export function normalizeScopeSelector(rawSelector) {
+  const namespaces = asStringArray(rawSelector?.namespace)
+    .concat(asStringArray(rawSelector?.namespaces))
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+  const tags = normalizeTagSelector(rawSelector?.tags);
+
+  return { namespaces, tags };
+}
+
+export function emptyScopeSelector() {
+  return { namespaces: [], tags: { mode: 'any', values: [] } };
+}
+
+export function normalizeProfileScopeSelectors(rawSelect) {
+  const normalized = {};
+
+  for (const type of SELECTABLE_TYPES) {
+    normalized[type] = normalizeScopeSelector(rawSelect?.[type]);
+  }
+
+  return normalized;
+}
+
+export function normalizeScopeMetadata(frontMatter) {
+  const scopeSource = frontMatter?.metadata?.scope || frontMatter?.scope || {};
+
+  const namespace = typeof scopeSource?.namespace === 'string'
+    ? scopeSource.namespace.trim()
+    : '';
+
+  const tags = asStringArray(scopeSource?.tags)
+    .map((value) => toKebabCase(value))
+    .filter(Boolean);
+
+  return {
+    namespace,
+    tags: [...new Set(tags)].sort((a, b) => a.localeCompare(b)),
+  };
+}
+
+export function matchesScope({ selector, metadata, fallbackCandidates = [] }) {
+  const hasSelector = selector.namespaces.length > 0 || selector.tags.values.length > 0;
+  if (!hasSelector) {
+    return true;
+  }
+
+  const namespaceCandidates = [metadata?.namespace, ...fallbackCandidates]
+    .filter((value) => typeof value === 'string' && value.trim().length > 0);
+
+  const matchedNamespaces = selector.namespaces.length === 0
+    ? true
+    : selector.namespaces.some((value) => namespaceCandidates.includes(value));
+
+  const metadataTags = new Set((metadata?.tags || []).map((value) => toKebabCase(value)));
+  const matchedTags = selector.tags.values.length === 0
+    ? true
+    : selector.tags.mode === 'all'
+      ? selector.tags.values.every((value) => metadataTags.has(value))
+      : selector.tags.values.some((value) => metadataTags.has(value));
+
+  return matchedNamespaces && matchedTags;
+}
+
+export function validateScopeMetadata({ metadata, allowedTags, sourcePath, errors, warnings }) {
+  const invalidTags = metadata.tags.filter((tag) => !allowedTags.has(tag));
+  for (const tag of invalidTags) {
+    errors.push(`Unknown scope tag \"${tag}\" in ${sourcePath}`);
+  }
+
+  if (metadata.namespace && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(metadata.namespace)) {
+    errors.push(`Invalid metadata.scope.namespace in ${sourcePath}. Use kebab-case.`);
+  }
+
+  if (!metadata.namespace && metadata.tags.length === 0) {
+    warnings.push(`Missing scope metadata in ${sourcePath}. Add metadata.scope.namespace or metadata.scope.tags.`);
+  }
+}
+
+export function hasSelector(selector) {
+  if (!selector) {
+    return false;
+  }
+  return selector.namespaces.length > 0 || selector.tags.values.length > 0;
+}
+
+export const selectableTypes = SELECTABLE_TYPES;

package/lib/util.mjs

@@ -0,0 +1,348 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJson(filePath) {
+  const text = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(text);
+}
+
+export async function writeJson(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  const text = `${JSON.stringify(value, null, 2)}\n`;
+  await fs.writeFile(filePath, text, 'utf8');
+}
+
+export async function removeDir(targetPath) {
+  await fs.rm(targetPath, { recursive: true, force: true });
+}
+
+export async function listFiles(rootDir) {
+  const result = [];
+
+  async function walk(currentDir) {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        result.push(fullPath);
+      }
+    }
+  }
+
+  if (await pathExists(rootDir)) {
+    await walk(rootDir);
+  }
+
+  return result;
+}
+
+export function toPosixPath(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+export function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+export async function sha256File(filePath) {
+  const content = await fs.readFile(filePath);
+  return sha256(content);
+}
+
+export function parseFrontMatter(markdownText) {
+  const normalized = markdownText.replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---\n')) {
+    return null;
+  }
+
+  const endIndex = normalized.indexOf('\n---\n', 4);
+  if (endIndex === -1) {
+    return null;
+  }
+
+  const frontMatterBlock = normalized.slice(4, endIndex);
+
+  function parseScalar(rawValue) {
+    const value = rawValue.trim();
+    if (value === '') {
+      return '';
+    }
+
+    if (value === 'true') {
+      return true;
+    }
+    if (value === 'false') {
+      return false;
+    }
+
+    if (/^-?\d+(?:\.\d+)?$/.test(value)) {
+      return Number(value);
+    }
+
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      if (!inner) {
+        return [];
+      }
+      return inner.split(',').map((part) => parseScalar(part.trim()));
+    }
+
+    return value.replace(/^['\"]|['\"]$/g, '');
+  }
+
+  function findNextMeaningful(lines, startIndex) {
+    for (let i = startIndex; i < lines.length; i += 1) {
+      const rawLine = lines[i];
+      const trimmed = rawLine.trim();
+      if (!trimmed || trimmed.startsWith('#')) {
+        continue;
+      }
+      return { line: rawLine, trimmed };
+    }
+    return null;
+  }
+
+  const lines = frontMatterBlock.split('\n');
+  const root = {};
+  const stack = [{ indent: -1, container: root, type: 'object' }];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index];
+    const trimmed = rawLine.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    const indent = rawLine.length - rawLine.trimStart().length;
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const frame = stack[stack.length - 1];
+
+    if (trimmed.startsWith('- ')) {
+      if (frame.type !== 'array') {
+        continue;
+      }
+
+      const valuePart = trimmed.slice(2).trim();
+      if (!valuePart) {
+        const objectValue = {};
+        frame.container.push(objectValue);
+        stack.push({ indent, container: objectValue, type: 'object' });
+        continue;
+      }
+
+      frame.container.push(parseScalar(valuePart));
+      continue;
+    }
+
+    const separatorIndex = trimmed.indexOf(':');
+    if (separatorIndex === -1 || frame.type !== 'object') {
+      continue;
+    }
+
+    const key = trimmed.slice(0, separatorIndex).trim();
+    const rawValue = trimmed.slice(separatorIndex + 1).trim();
+    if (rawValue) {
+      frame.container[key] = parseScalar(rawValue);
+      continue;
+    }
+
+    const next = findNextMeaningful(lines, index + 1);
+    const shouldUseArray = Boolean(next && next.line.length - next.line.trimStart().length > indent && next.trimmed.startsWith('- '));
+
+    if (shouldUseArray) {
+      const arrayValue = [];
+      frame.container[key] = arrayValue;
+      stack.push({ indent, container: arrayValue, type: 'array' });
+    } else {
+      const objectValue = {};
+      frame.container[key] = objectValue;
+      stack.push({ indent, container: objectValue, type: 'object' });
+    }
+  }
+
+  return root;
+}
+
+export function parseCliArgs(argv) {
+  const options = {};
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+
+    const [key, directValue] = token.slice(2).split('=');
+    if (directValue !== undefined) {
+      options[key] = directValue;
+      continue;
+    }
+
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      options[key] = true;
+    } else {
+      options[key] = next;
+      i += 1;
+    }
+  }
+
+  return { options, positional };
+}
+
+export function asArray(value) {
+  if (!value) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+export function createLogger({ quiet = false } = {}) {
+  return {
+    info(message) {
+      if (!quiet) {
+        console.log(message);
+      }
+    },
+    warn(message) {
+      console.warn(message);
+    },
+    error(message) {
+      console.error(message);
+    },
+  };
+}
+
+function serializeYamlValue(value, indent = 0) {
+  const prefix = ' '.repeat(indent);
+
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  if (typeof value === 'boolean' || typeof value === 'number') {
+    return String(value);
+  }
+
+  if (typeof value === 'string') {
+    if (value.includes('\n') || value.includes(':') || value.includes('#')) {
+      return `"${value.replace(/"/g, '\\"')}"`;
+    }
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return '[]';
+    }
+    if (value.every((item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean')) {
+      return `[${value.map((item) => serializeYamlValue(item, 0)).join(', ')}]`;
+    }
+    const lines = value.map((item) => {
+      if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+        const objectLines = Object.entries(item)
+          .map(([key, val]) => `${prefix}  ${key}: ${serializeYamlValue(val, indent + 2)}`)
+          .join('\n');
+        return `${prefix}- \n${objectLines}`;
+      }
+      return `${prefix}- ${serializeYamlValue(item, indent + 2)}`;
+    });
+    return `\n${lines.join('\n')}`;
+  }
+
+  if (typeof value === 'object') {
+    const lines = [];
+    for (const [key, val] of Object.entries(value)) {
+      if (typeof val === 'object' && val !== null) {
+        lines.push(`${prefix}${key}:${serializeYamlValue(val, indent + 2)}`);
+      } else {
+        lines.push(`${prefix}${key}: ${serializeYamlValue(val, indent + 2)}`);
+      }
+    }
+    return `\n${lines.join('\n')}`;
+  }
+
+  return String(value);
+}
+
+export function stripScopeFrontMatter(content) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---\n')) {
+    return content;
+  }
+
+  const endIndex = normalized.indexOf('\n---\n', 4);
+  if (endIndex === -1) {
+    return content;
+  }
+
+  const frontMatter = parseFrontMatter(content);
+  if (!frontMatter) {
+    return content;
+  }
+
+  const hasMetadataScope = Boolean(frontMatter?.metadata?.scope);
+  const hasLegacyScope = Boolean(frontMatter?.scope);
+  if (!hasMetadataScope && !hasLegacyScope) {
+    return content;
+  }
+
+  const bodyContent = normalized.slice(endIndex + 5);
+  const { scope: _legacyScope, ...baseFields } = frontMatter;
+  const metadata = baseFields.metadata && typeof baseFields.metadata === 'object' && !Array.isArray(baseFields.metadata)
+    ? baseFields.metadata
+    : null;
+
+  let remainingFields = baseFields;
+  if (metadata && Object.prototype.hasOwnProperty.call(metadata, 'scope')) {
+    const { scope: _metadataScope, ...remainingMetadata } = metadata;
+    if (Object.keys(remainingMetadata).length === 0) {
+      const { metadata: _removedMetadata, ...withoutMetadata } = baseFields;
+      remainingFields = withoutMetadata;
+    } else {
+      remainingFields = {
+        ...baseFields,
+        metadata: remainingMetadata,
+      };
+    }
+  }
+
+  if (Object.keys(remainingFields).length === 0) {
+    return bodyContent;
+  }
+
+  const yamlLines = [];
+  for (const [key, value] of Object.entries(remainingFields)) {
+    const serialized = serializeYamlValue(value, 0);
+    if (serialized.startsWith('\n')) {
+      yamlLines.push(`${key}:${serialized}`);
+    } else {
+      yamlLines.push(`${key}: ${serialized}`);
+    }
+  }
+
+  return `---\n${yamlLines.join('\n')}\n---\n${bodyContent}`;
+}

package/lib/validate.mjs

@@ -0,0 +1,209 @@
+import fs from 'node:fs/promises';
+import { parseFrontMatter } from './util.mjs';
+import {
+  hasSelector,
+  normalizeScopeMetadata,
+  selectableTypes,
+  validateScopeMetadata,
+} from './scope.mjs';
+
+function pushError(errors, message) {
+  errors.push(message);
+}
+
+function pushWarning(warnings, message) {
+  warnings.push(message);
+}
+
+export async function validatePlan({ preset, skillDefinitions, promptDefinitions, subagentDefinitions }) {
+  const errors = [];
+  const warnings = [];
+  const allowedTags = new Set(Array.isArray(preset.scopeTags) ? preset.scopeTags : []);
+
+  for (const layer of preset.layers || []) {
+    for (const type of selectableTypes) {
+      const selector = layer.select?.[type];
+      if (!selector) {
+        continue;
+      }
+
+      if (!['any', 'all'].includes(selector.tags?.mode)) {
+        pushError(errors, `Invalid tags.mode in layers.${layer.name}.select.${type}. Use "any" or "all".`);
+      }
+
+      for (const tag of selector.tags?.values || []) {
+        if (!allowedTags.has(tag)) {
+          pushError(errors, `Unknown tag "${tag}" in layers.${layer.name}.select.${type}.`);
+        }
+      }
+
+      for (const namespace of selector.namespaces || []) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(namespace)) {
+          pushError(errors, `Invalid namespace "${namespace}" in layers.${layer.name}.select.${type}. Use kebab-case.`);
+        }
+      }
+    }
+  }
+
+  const skillByName = new Map();
+  for (const skill of skillDefinitions) {
+    const text = await fs.readFile(skill.skillFilePath, 'utf8').catch(() => null);
+    if (text === null) {
+      pushError(errors, `Missing SKILL.md for skill "${skill.name}" at ${skill.skillFilePath}`);
+      continue;
+    }
+
+    const fm = parseFrontMatter(text);
+    if (!fm) {
+      pushError(errors, `Missing YAML front matter in ${skill.skillFilePath}`);
+      continue;
+    }
+
+    if (!fm.name) {
+      pushError(errors, `Missing front matter field "name" in ${skill.skillFilePath}`);
+      continue;
+    }
+
+    if (!fm.description) {
+      pushError(errors, `Missing front matter field "description" in ${skill.skillFilePath}`);
+    }
+
+    validateScopeMetadata({
+      metadata: normalizeScopeMetadata(fm),
+      allowedTags,
+      sourcePath: skill.skillFilePath,
+      errors,
+      warnings,
+    });
+
+    if (fm.name !== skill.name) {
+      pushError(
+        errors,
+        `Skill name mismatch: folder "${skill.name}" but front matter name "${fm.name}" in ${skill.skillFilePath}`
+      );
+    }
+
+    if (!fm.name.includes('.') && !fm.name.includes('-')) {
+      pushWarning(
+        warnings,
+        `Skill "${fm.name}" has no prefix. Consider names like "francisco.topic.purpose" or "fh-topic-purpose".`
+      );
+    }
+
+    if (skillByName.has(fm.name)) {
+      const previous = skillByName.get(fm.name);
+      pushError(
+        errors,
+        `Duplicate skill name "${fm.name}" across layers: ${previous.layer} and ${skill.layer}`
+      );
+    } else {
+      skillByName.set(fm.name, skill);
+    }
+  }
+
+  const promptNames = new Map();
+  for (const prompt of promptDefinitions) {
+    const key = prompt.name.toLowerCase();
+    if (!prompt.name.endsWith('.prompt.md')) {
+      pushError(errors, `Prompt must end with .prompt.md: ${prompt.sourcePath}`);
+      continue;
+    }
+
+    if (promptNames.has(key)) {
+      const previous = promptNames.get(key);
+      pushError(
+        errors,
+        `Prompt collision on destination ${prompt.name} across layers: ${previous.layer} and ${prompt.layer}`
+      );
+    } else {
+      promptNames.set(key, prompt);
+    }
+  }
+
+  const seenSubagentsByTarget = new Map();
+  for (const agent of subagentDefinitions) {
+    if (!seenSubagentsByTarget.has(agent.target)) {
+      seenSubagentsByTarget.set(agent.target, new Map());
+    }
+
+    const perTarget = seenSubagentsByTarget.get(agent.target);
+    const key = agent.id.toLowerCase();
+    if (perTarget.has(key)) {
+      const previous = perTarget.get(key);
+      pushError(
+        errors,
+        `Subagent collision for target "${agent.target}" with id "${agent.id}" across layers: ${previous.layer} and ${agent.layer}`
+      );
+    } else {
+      perTarget.set(key, agent);
+    }
+
+    const text = await fs.readFile(agent.sourcePath, 'utf8');
+    const fm = parseFrontMatter(text);
+    if (fm) {
+      if (!fm.name) {
+        pushError(errors, `Missing front matter field "name" in subagent file ${agent.sourcePath}`);
+      }
+      if (!fm.description) {
+        pushError(errors, `Missing front matter field "description" in subagent file ${agent.sourcePath}`);
+      }
+
+      validateScopeMetadata({
+        metadata: normalizeScopeMetadata(fm),
+        allowedTags,
+        sourcePath: agent.sourcePath,
+        errors,
+        warnings,
+      });
+    }
+
+    if (agent.target === 'copilot' && !agent.name.endsWith('.agent.md')) {
+      pushError(errors, `Copilot subagent output must end with .agent.md: ${agent.name}`);
+    }
+  }
+
+  const perLayerCounts = new Map();
+  for (const layer of preset.layers || []) {
+    perLayerCounts.set(layer.name, {
+      skills: 0,
+      prompts: 0,
+      subagents: 0,
+    });
+  }
+
+  for (const skill of skillDefinitions) {
+    if (perLayerCounts.has(skill.layer)) {
+      perLayerCounts.get(skill.layer).skills += 1;
+    }
+  }
+
+  for (const prompt of promptDefinitions) {
+    if (perLayerCounts.has(prompt.layer)) {
+      perLayerCounts.get(prompt.layer).prompts += 1;
+    }
+  }
+
+  for (const subagent of subagentDefinitions) {
+    if (subagent.target !== 'portable') {
+      continue;
+    }
+    if (perLayerCounts.has(subagent.layer)) {
+      perLayerCounts.get(subagent.layer).subagents += 1;
+    }
+  }
+
+  for (const layer of preset.layers || []) {
+    const counts = perLayerCounts.get(layer.name) || { skills: 0, prompts: 0, subagents: 0 };
+    if (hasSelector(layer.select?.skills) && counts.skills === 0) {
+      pushWarning(warnings, `layers.${layer.name}.select.skills matched no files.`);
+    }
+    if (hasSelector(layer.select?.prompts) && counts.prompts === 0) {
+      pushWarning(warnings, `layers.${layer.name}.select.prompts matched no files.`);
+    }
+    if (hasSelector(layer.select?.subagents) && counts.subagents === 0) {
+      pushWarning(warnings, `layers.${layer.name}.select.subagents matched no files.`);
+    }
+  }
+
+  return { errors, warnings };
+}