showdar-skills 0.2.0

package/src/project.js

@@ -0,0 +1,287 @@
+import { access, cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { globalCommandRootFor, globalSkillRootFor, NATIVE_TARGETS, opencodeCommandRoot, resolveTargets, skillRootFor } from './adapters.js';
+
+const PROJECT_MANIFEST = '.showdar.json';
+const START = '<!-- showdar-skills:start -->';
+const END = '<!-- showdar-skills:end -->';
+
+export function globalManifestPath(homeRoot = homedir()) {
+  return path.join(homeRoot, '.showdar', 'global.json');
+}
+
+async function exists(target) {
+  try { await access(target); return true; } catch { return false; }
+}
+
+async function hashTree(target) {
+  const h = createHash('sha256');
+  async function walk(current, relative = '') {
+    const info = await stat(current);
+    if (info.isDirectory()) {
+      const entries = await readdir(current, { withFileTypes: true });
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) await walk(path.join(current, entry.name), path.join(relative, entry.name));
+      return;
+    }
+    h.update(relative.replaceAll(path.sep, '/'));
+    h.update('\0');
+    h.update(await readFile(current));
+    h.update('\0');
+  }
+  await walk(target);
+  return h.digest('hex');
+}
+
+async function readManifest(manifestPath) {
+  if (!(await exists(manifestPath))) return null;
+  try { return JSON.parse(await readFile(manifestPath, 'utf8')); }
+  catch (error) { throw new Error(`Invalid Showdar manifest: ${error.message}`); }
+}
+
+async function writeJsonAtomic(target, value) {
+  const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  await rename(tmp, target);
+}
+
+function managedBlock(skillIds) {
+  const routes = [
+    ['map repository architecture, dependencies, or impact', 'showdar-understand'],
+    ['plan implementation of agreed behavior and scope', 'showdar-plan'],
+    ['design product UI, UX, responsive layout, accessibility, or visual polish', 'showdar-design'],
+    ['implement or refactor an agreed application change', 'showdar-build'],
+    ['debug an observed bug, crash, regression, build, or performance failure', 'showdar-debug'],
+    ['choose or implement automated tests and coverage', 'showdar-test'],
+    ['review code or diffs for general correctness, architecture, performance, maintainability, or tests', 'showdar-review'],
+    ['upgrade dependencies, frameworks, runtimes, or platforms', 'showdar-upgrade'],
+    ['check release, artifact, or handoff readiness', 'showdar-ship'],
+    ['recover interrupted or partial engineering work', 'showdar-recover'],
+    ['perform local Git inspection, staging, commit, merge, rebase, or conflict work', 'showdar-git'],
+    ['define product behavior, business rules, ambiguity, or acceptance criteria', 'showdar-requirements'],
+    ['plan QA scenarios, risk coverage, regression, compatibility, or bug evidence', 'showdar-quality'],
+    ['assess threats, attack surface, trust boundaries, auth, secrets, exposure, or exploitability', 'showdar-security'],
+    ['inspect or change CI/CD, containers, environments, deployment, observability, rollback, or runtime operations', 'showdar-ops'],
+  ].filter(([, id]) => skillIds.includes(id));
+  const lines = routes.map(([intent, skill]) => `- ${intent} -> \`${skill}\``).join('\n');
+  return `${START}\n## Showdar Skills routing\n\nUse the smallest Showdar skill that fully matches the current task. Do not load unrelated Showdar skills.\n\n${lines}\n\nFor debugging, gather evidence before modifying code. For shipping or destructive operations, require explicit user approval and fresh verification. Never print or commit secrets.\n${END}`;
+}
+
+function stripManagedBlock(content) {
+  const start = content.indexOf(START);
+  if (start === -1) return content;
+  const end = content.indexOf(END, start);
+  if (end === -1) throw new Error('AGENTS.md contains an incomplete Showdar managed block. Repair it manually before continuing.');
+  const before = content.slice(0, start).trimEnd();
+  const after = content.slice(end + END.length).trimStart();
+  return [before, after].filter(Boolean).join('\n\n');
+}
+
+async function writeAgentsBlock(projectRoot, skillIds) {
+  const target = path.join(projectRoot, 'AGENTS.md');
+  const current = (await exists(target)) ? await readFile(target, 'utf8') : '';
+  const clean = stripManagedBlock(current).trimEnd();
+  const block = managedBlock(skillIds);
+  await writeFile(target, clean ? `${clean}\n\n${block}\n` : `${block}\n`);
+}
+
+async function removeAgentsBlock(projectRoot) {
+  const target = path.join(projectRoot, 'AGENTS.md');
+  if (!(await exists(target))) return;
+  const current = await readFile(target, 'utf8');
+  const clean = stripManagedBlock(current).trim();
+  if (clean) await writeFile(target, `${clean}\n`);
+  else await rm(target, { force: true });
+}
+
+function ownedPathSet(manifest) {
+  return new Set((manifest?.files ?? []).map((entry) => entry.path));
+}
+
+function safeOwnedPath(baseRoot, relative, allowedRoots = []) {
+  if (typeof relative !== 'string' || !relative) return null;
+  const roots = [baseRoot, ...allowedRoots].map((root) => path.resolve(root));
+  const target = path.resolve(relative.startsWith(path.sep) ? relative : path.join(roots[0], relative));
+  if (!roots.some((root) => target === root || target.startsWith(`${root}${path.sep}`))) return null;
+  return target;
+}
+
+function manifestPathFor(baseRoot, destination) {
+  const relative = path.relative(baseRoot, destination);
+  return relative.replaceAll(path.sep, '/');
+}
+
+async function copyOwned({ baseRoot, source, destination, priorOwned, newFiles }) {
+  const relative = manifestPathFor(baseRoot, destination);
+  if ((await exists(destination)) && !priorOwned.has(relative)) {
+    throw new Error(`Refusing to overwrite existing non-Showdar-managed skill or command: ${destination}`);
+  }
+  await rm(destination, { recursive: true, force: true });
+  await mkdir(path.dirname(destination), { recursive: true });
+  await cp(source, destination, { recursive: true });
+  newFiles.push({ path: relative, hash: await hashTree(destination) });
+}
+
+async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0', scope, skillRootForTarget, commandRoot, managedRoots = [] }) {
+  await mkdir(baseRoot, { recursive: true });
+  const targets = resolveTargets(ai);
+  const prior = await readManifest(manifestPath);
+  const priorOwned = ownedPathSet(prior);
+  const desiredPaths = new Set();
+
+  const skillRoots = new Map();
+  for (const target of targets) {
+    const root = skillRootForTarget(target);
+    skillRoots.set(path.resolve(root), root);
+  }
+  for (const root of skillRoots.values()) {
+    for (const skillId of skillIds) desiredPaths.add(manifestPathFor(baseRoot, path.join(root, skillId)));
+  }
+  if (targets.includes('opencode')) {
+    for (const name of commandNames) desiredPaths.add(manifestPathFor(baseRoot, path.join(commandRoot(), `${name}.md`)));
+  }
+
+  for (const entry of prior?.files ?? []) {
+    const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
+    if (target && !desiredPaths.has(entry.path)) await rm(target, { recursive: true, force: true });
+  }
+
+  const files = [];
+  for (const root of skillRoots.values()) {
+    for (const skillId of skillIds) {
+      const source = path.join(packageRoot, 'skills', skillId);
+      if (!(await exists(path.join(source, 'SKILL.md')))) throw new Error(`Skill asset not found: ${skillId}`);
+      await copyOwned({ baseRoot, source, destination: path.join(root, skillId), priorOwned, newFiles: files });
+    }
+  }
+
+  if (targets.includes('opencode')) {
+    const root = commandRoot();
+    for (const name of commandNames) {
+      const source = path.join(packageRoot, 'commands', 'opencode', 'showdar', `${name}.md`);
+      if (!(await exists(source))) throw new Error(`OpenCode command asset not found: ${name}`);
+      await copyOwned({ baseRoot, source, destination: path.join(root, `${name}.md`), priorOwned, newFiles: files });
+    }
+  }
+
+  const manifest = {
+    version: 2,
+    scope,
+    packageVersion,
+    profile,
+    ai,
+    targets,
+    skills: [...skillIds],
+    commands: targets.includes('opencode') ? [...commandNames] : [],
+    files,
+  };
+  await mkdir(path.dirname(manifestPath), { recursive: true });
+  await writeJsonAtomic(manifestPath, manifest);
+  if (agentsRoot) await writeAgentsBlock(agentsRoot, skillIds);
+  return inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope });
+}
+
+export async function initProject({ projectRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0' }) {
+  return initInstallation({
+    baseRoot: projectRoot,
+    manifestPath: path.join(projectRoot, PROJECT_MANIFEST),
+    agentsRoot: projectRoot,
+    packageRoot,
+    profile,
+    ai,
+    skillIds,
+    commandNames,
+    packageVersion,
+    scope: 'project',
+    skillRootForTarget: (target) => skillRootFor(target, projectRoot),
+    commandRoot: () => opencodeCommandRoot(projectRoot),
+  });
+}
+
+export async function initGlobal({ homeRoot = homedir(), packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0' }) {
+  const managedRoots = [...new Set(NATIVE_TARGETS.map((target) => globalSkillRootFor(target, { homeRoot }))), globalCommandRootFor({ homeRoot })];
+  return initInstallation({
+    baseRoot: homeRoot,
+    manifestPath: globalManifestPath(homeRoot),
+    agentsRoot: null,
+    packageRoot,
+    profile,
+    ai,
+    skillIds,
+    commandNames,
+    packageVersion,
+    scope: 'global',
+    skillRootForTarget: (target) => globalSkillRootFor(target, { homeRoot }),
+    commandRoot: () => globalCommandRootFor({ homeRoot }),
+    managedRoots,
+  });
+}
+
+async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope, managedRoots = [] }) {
+  let manifest;
+  try { manifest = await readManifest(manifestPath); }
+  catch (error) { return { installed: true, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, commands: 0, issues: [error.message] }; }
+  if (!manifest) return { installed: false, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, commands: 0, issues: ['Showdar is not installed.'] };
+
+  const issues = [];
+  for (const entry of manifest.files ?? []) {
+    const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
+    if (!target) { issues.push(`Invalid managed path: ${entry.path}`); continue; }
+    if (!(await exists(target))) { issues.push(`Missing managed path: ${entry.path}`); continue; }
+    const actual = await hashTree(target);
+    if (actual !== entry.hash) issues.push(`Managed path drift detected: ${entry.path}`);
+  }
+
+  if (agentsRoot) {
+    const agentsFile = path.join(agentsRoot, 'AGENTS.md');
+    if (!(await exists(agentsFile))) issues.push('Missing AGENTS.md routing block');
+    else {
+      const text = await readFile(agentsFile, 'utf8');
+      if (!text.includes(START) || !text.includes(END)) issues.push('Missing Showdar AGENTS.md managed block');
+    }
+  }
+
+  return {
+    installed: true,
+    healthy: issues.length === 0,
+    scope: manifest.scope ?? scope,
+    profile: manifest.profile ?? null,
+    ai: manifest.ai ?? null,
+    targets: manifest.targets ?? [],
+    skills: (manifest.skills ?? []).length,
+    commands: (manifest.commands ?? []).length,
+    issues,
+  };
+}
+
+async function removeInstallation({ baseRoot, manifestPath, agentsRoot, managedRoots = [] }) {
+  let manifest;
+  try { manifest = await readManifest(manifestPath); }
+  catch { manifest = null; }
+  for (const entry of manifest?.files ?? []) {
+    const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
+    if (target) await rm(target, { recursive: true, force: true });
+  }
+  await rm(manifestPath, { force: true });
+  if (agentsRoot) await removeAgentsBlock(agentsRoot);
+}
+
+export async function inspectProject(projectRoot) {
+  return inspectInstallation({ baseRoot: projectRoot, manifestPath: path.join(projectRoot, PROJECT_MANIFEST), agentsRoot: projectRoot, scope: 'project' });
+}
+
+export async function inspectGlobal({ homeRoot = homedir() } = {}) {
+  const managedRoots = [...new Set(NATIVE_TARGETS.map((target) => globalSkillRootFor(target, { homeRoot }))), globalCommandRootFor({ homeRoot })];
+  return inspectInstallation({ baseRoot: homeRoot, manifestPath: globalManifestPath(homeRoot), agentsRoot: null, scope: 'global', managedRoots });
+}
+
+export async function removeProject(projectRoot) {
+  await removeInstallation({ baseRoot: projectRoot, manifestPath: path.join(projectRoot, PROJECT_MANIFEST), agentsRoot: projectRoot });
+}
+
+export async function removeGlobal({ homeRoot = homedir() } = {}) {
+  const managedRoots = [...new Set(NATIVE_TARGETS.map((target) => globalSkillRootFor(target, { homeRoot }))), globalCommandRootFor({ homeRoot })];
+  await removeInstallation({ baseRoot: homeRoot, manifestPath: globalManifestPath(homeRoot), agentsRoot: null, managedRoots });
+}

package/src/runtime.js

@@ -0,0 +1,9 @@
+export const CANONICAL_RUNTIME_FILE = 'engine/detect-stack.mjs';
+
+export const VENDORED_RUNTIME_FILES = Object.freeze([
+  'skills/showdar-debug/scripts/lib/detect-stack.mjs',
+  'skills/showdar-plan/scripts/lib/detect-stack.mjs',
+  'skills/showdar-ship/scripts/lib/detect-stack.mjs',
+  'skills/showdar-understand/scripts/lib/detect-stack.mjs',
+  'skills/showdar-upgrade/scripts/lib/detect-stack.mjs',
+]);

package/src/validate.js

@@ -0,0 +1,310 @@
+import { access, readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SKILLS, PROFILES } from './catalog.js';
+import { CANONICAL_RUNTIME_FILE, VENDORED_RUNTIME_FILES } from './runtime.js';
+import { parseCsv } from '../engine/csv.mjs';
+
+export const STACK_IDS = new Set([
+  'android', 'android-testing', 'ci', 'cocoapods', 'compose', 'dart', 'detox', 'docker', 'electron',
+  'expo', 'fastify', 'flutter', 'flutter-test', 'gradle', 'html-tailwind', 'integration_test', 'ios',
+  'jest', 'kotlin', 'kubernetes', 'nestjs', 'nextjs', 'node', 'node-fastify', 'nuxt', 'package-manager',
+  'playwright', 'react', 'react-native', 'react-testing-library', 'rust', 'svelte', 'spm', 'swift',
+  'swiftui', 'tauri', 'typescript', 'vitest', 'vue', 'workspace', 'xctest',
+]);
+
+export const REQUIRED_SECTIONS = [
+  'Purpose',
+  'When to use',
+  'When not to use',
+  'Inputs and assumptions',
+  'Non-negotiable rules',
+  'Workflow',
+  'Decision points',
+  'Stack detection',
+  'Failure modes',
+  'Stop conditions',
+  'Escalation conditions',
+  'Verification',
+  'Output contract',
+  'Anti-patterns',
+  'Example',
+];
+
+async function exists(target) {
+  try { await access(target); return true; } catch { return false; }
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---\n', 4);
+  if (end === -1) return {};
+  const out = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    const i = line.indexOf(':');
+    if (i <= 0) continue;
+    out[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^['"]|['"]$/g, '');
+  }
+  return out;
+}
+
+function meaningfulLines(text) {
+  return text.split(/\r?\n/).filter((line) => {
+    const value = line.trim();
+    return value && value !== '---' && !value.startsWith('#') && !/^[\-*]?$/.test(value);
+  }).length;
+}
+
+function referencedLocalAssets(text) {
+  const code = [...text.matchAll(/`((?:references|data|stacks|scripts|examples)\/[^`\n]+)`/g)].map((match) => match[1]);
+  const links = [...text.matchAll(/\]\(((?:references|data|stacks|scripts|examples)\/[^)#\s]+)(?:#[^)\s]+)?\)/g)].map((match) => match[1]);
+  return [...new Set([...code, ...links])];
+}
+
+function safeRelativePath(value) {
+  return typeof value === 'string' && value.length > 0 && !path.isAbsolute(value) && !value.split(/[\\/]/).includes('..');
+}
+
+export async function validateSkillDirectory(skillDir, { minMeaningfulLines = 60 } = {}) {
+  const errors = [];
+  const warnings = [];
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  if (!(await exists(skillFile))) return { ok: false, errors: ['missing SKILL.md'], warnings };
+
+  const text = await readFile(skillFile, 'utf8');
+  const frontmatter = parseFrontmatter(text);
+  const basename = path.basename(skillDir);
+
+  if (!frontmatter.name) errors.push('frontmatter is missing name');
+  else if (frontmatter.name !== basename) errors.push(`frontmatter name "${frontmatter.name}" does not match directory "${basename}"`);
+  if (!frontmatter.description || frontmatter.description.length < 30) errors.push('frontmatter description must be at least 30 characters');
+
+  for (const section of REQUIRED_SECTIONS) {
+    const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (!new RegExp(`^##\\s+${escaped}\\s*$`, 'mi').test(text)) errors.push(`missing section: ${section}`);
+  }
+
+  const lines = meaningfulLines(text);
+  if (lines < minMeaningfulLines) errors.push(`SKILL.md has ${lines} meaningful lines; expected at least ${minMeaningfulLines}`);
+
+  const placeholder = text.match(/\b(TODO|TBD|FIXME)\b|fill\s+(?:this\s+)?later|lorem ipsum|placeholder content/i);
+  if (placeholder) errors.push(`placeholder marker found: ${placeholder[0]}`);
+
+  for (const relative of referencedLocalAssets(text)) {
+    if (!(await exists(path.join(skillDir, relative)))) errors.push(`referenced asset does not exist: ${relative}`);
+  }
+
+  async function validateScripts(dir) {
+    if (!(await exists(dir))) return;
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const target = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await validateScripts(target);
+        continue;
+      }
+      if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.js')) continue;
+      const syntax = spawnSync(process.execPath, ['--check', target], { encoding: 'utf8' });
+      if (syntax.status !== 0) errors.push(`script ${path.relative(skillDir, target)} is not runnable JavaScript: ${(syntax.stderr || syntax.stdout).trim()}`);
+      const source = await readFile(target, 'utf8');
+      const imports = [
+        ...source.matchAll(/(?:from\s+|import\s*)['"](\.{1,2}\/[^'"]+)['"]/g),
+      ].map((match) => match[1]);
+      for (const specifier of imports) {
+        const resolved = path.resolve(path.dirname(target), specifier);
+        if (!(await exists(resolved))) {
+          errors.push(`script ${path.relative(skillDir, target)} has missing relative import: ${specifier}`);
+        }
+      }
+    }
+  }
+  await validateScripts(path.join(skillDir, 'scripts'));
+  await validateCsvFiles(skillDir, errors);
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+async function validateCsvFiles(skillDir, errors) {
+  const dataDir = path.join(skillDir, 'data');
+  const csvFiles = [];
+  async function walk(dir) {
+    if (!(await exists(dir))) return;
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const target = path.join(dir, entry.name);
+      if (entry.isDirectory()) await walk(target);
+      else if (entry.name.endsWith('.csv')) csvFiles.push(target);
+    }
+  }
+  await walk(dataDir);
+  if (!csvFiles.length) return;
+
+  const indexFile = path.join(dataDir, 'index.json');
+  if (!(await exists(indexFile))) {
+    errors.push('data contains CSV datasets but is missing data/index.json');
+    return;
+  }
+
+  let index;
+  try { index = JSON.parse(await readFile(indexFile, 'utf8')); }
+  catch (error) { errors.push(`data/index.json is invalid JSON: ${error.message}`); return; }
+  if (index.version !== 1) errors.push('data/index.json must declare version 1');
+  if (index.skill !== path.basename(skillDir)) errors.push('data/index.json skill does not match directory');
+  if (!Array.isArray(index.datasets) || !index.datasets.length) { errors.push('data/index.json must list at least one dataset'); return; }
+
+  const indexed = new Set();
+  for (const dataset of index.datasets) {
+    if (!dataset || typeof dataset !== 'object' || Array.isArray(dataset)) {
+      errors.push('data/index.json contains a dataset that is not an object');
+      continue;
+    }
+    const listFields = (name) => {
+      const value = dataset[name];
+      if (value === undefined) return [];
+      if (!Array.isArray(value) || value.some((field) => typeof field !== 'string' || !field.trim())) {
+        errors.push(`data/index.json ${name} must be an array of non-empty strings`);
+        return [];
+      }
+      const unique = new Set(value);
+      if (unique.size !== value.length) errors.push(`data/index.json ${name} contains duplicates`);
+      return value;
+    };
+    const requiredColumns = listFields('requiredColumns');
+    const searchableFields = listFields('searchableFields');
+    const filterFields = listFields('filterFields');
+    if (dataset.idField !== undefined && (typeof dataset.idField !== 'string' || !dataset.idField.trim())) {
+      errors.push('data/index.json idField must be a non-empty string');
+    }
+    const relative = dataset?.file;
+    if (!safeRelativePath(relative) || !relative.endsWith('.csv')) { errors.push(`invalid indexed dataset path: ${relative ?? '<missing>'}`); continue; }
+    if (indexed.has(relative)) errors.push(`duplicate indexed dataset: ${relative}`);
+    indexed.add(relative);
+    const target = path.join(skillDir, relative);
+    if (!(await exists(target))) { errors.push(`indexed dataset does not exist: ${relative}`); continue; }
+    let rows;
+    try { rows = parseCsv(await readFile(target, 'utf8')); }
+    catch (error) { errors.push(`${relative} is malformed CSV: ${error.message}`); continue; }
+    if (!rows.length) { errors.push(`${relative} is an empty dataset`); continue; }
+    const columns = Object.keys(rows[0]);
+    const required = [...new Set([...requiredColumns, dataset.idField].filter(Boolean))];
+    for (const column of required) if (!columns.includes(column)) errors.push(`${relative} is missing required column: ${column}`);
+    for (const column of [...searchableFields, ...filterFields]) {
+      if (!columns.includes(column)) errors.push(`${relative} indexes missing column: ${column}`);
+    }
+    const rowKeys = new Set();
+    const idKeys = new Set();
+    for (const row of rows) {
+      const rowKey = JSON.stringify(columns.map((column) => row[column] ?? ''));
+      if (rowKeys.has(rowKey)) errors.push(`${relative} contains duplicate row`);
+      rowKeys.add(rowKey);
+      if (dataset.idField) {
+        const id = String(row[dataset.idField] ?? '').trim();
+        if (!id) errors.push(`${relative} contains an empty ${dataset.idField}`);
+        else if (idKeys.has(id)) errors.push(`${relative} contains duplicate id: ${id}`);
+        idKeys.add(id);
+      }
+      for (const column of ['stack', 'stacks']) {
+        for (const stack of String(row[column] ?? '').split(/[,;|]/).map((value) => value.trim()).filter(Boolean)) {
+          if (stack !== '*' && !STACK_IDS.has(stack)) errors.push(`${relative} has invalid stack: ${stack}`);
+        }
+      }
+      if (row.reference && (!safeRelativePath(row.reference) || !(await exists(path.join(skillDir, row.reference))))) {
+        errors.push(`${relative} references missing asset: ${row.reference}`);
+      }
+    }
+    if (dataset.reference && (!safeRelativePath(dataset.reference) || !(await exists(path.join(skillDir, dataset.reference))))) {
+      errors.push(`${relative} references missing asset: ${dataset.reference}`);
+    }
+  }
+  for (const target of csvFiles) {
+    const relative = path.relative(skillDir, target).replaceAll(path.sep, '/');
+    if (!indexed.has(relative)) errors.push(`${relative} is not listed in data/index.json`);
+  }
+}
+
+export async function validateRepository(packageRoot) {
+  const errors = [];
+  const warnings = [];
+  const known = new Set(SKILLS.map((skill) => skill.id));
+  const skillsRoot = path.join(packageRoot, 'skills');
+
+  for (const skill of SKILLS) {
+    const dir = path.join(skillsRoot, skill.id);
+    const result = await validateSkillDirectory(dir);
+    for (const error of result.errors) errors.push(`${skill.id}: ${error}`);
+    warnings.push(...result.warnings.map((warning) => `${skill.id}: ${warning}`));
+  }
+
+  let canonicalRuntime;
+  try {
+    canonicalRuntime = await readFile(path.join(packageRoot, CANONICAL_RUNTIME_FILE));
+  } catch (error) {
+    errors.push(`missing canonical runtime detector: ${CANONICAL_RUNTIME_FILE} (${error.message})`);
+  }
+  if (canonicalRuntime) {
+    for (const relative of VENDORED_RUNTIME_FILES) {
+      try {
+        const vendoredRuntime = await readFile(path.join(packageRoot, relative));
+        if (!vendoredRuntime.equals(canonicalRuntime)) errors.push(`vendored runtime detector drift: ${relative} differs from ${CANONICAL_RUNTIME_FILE}`);
+      } catch (error) {
+        errors.push(`missing vendored runtime detector: ${relative} (${error.message})`);
+      }
+    }
+  }
+
+  if (await exists(skillsRoot)) {
+    for (const entry of await readdir(skillsRoot, { withFileTypes: true })) {
+      if (entry.isDirectory() && entry.name.startsWith('showdar-') && !known.has(entry.name)) errors.push(`unexpected skill directory: ${entry.name}`);
+    }
+  }
+
+  for (const [profile, ids] of Object.entries(PROFILES)) {
+    const seen = new Set();
+    for (const id of ids) {
+      if (!known.has(id)) errors.push(`profile ${profile} references unknown skill ${id}`);
+      if (seen.has(id)) errors.push(`profile ${profile} duplicates skill ${id}`);
+      seen.add(id);
+    }
+    const profileFile = path.join(packageRoot, 'profiles', `${profile}.json`);
+    if (!(await exists(profileFile))) errors.push(`missing profile file: profiles/${profile}.json`);
+    else {
+      try {
+        const disk = JSON.parse(await readFile(profileFile, 'utf8'));
+        if (JSON.stringify(disk.skills ?? []) !== JSON.stringify(ids)) errors.push(`profile file ${profile}.json does not match catalog`);
+      } catch (error) { errors.push(`invalid profile file ${profile}.json: ${error.message}`); }
+    }
+  }
+
+  const relationshipFiles = [
+    'router/skill-map.yaml', 'router/triggers.yaml', 'router/conflicts.yaml',
+    'bundles/bugfix.yaml', 'bundles/feature.yaml', 'bundles/design.yaml', 'bundles/upgrade.yaml', 'bundles/release.yaml',
+  ];
+  for (const relative of relationshipFiles) {
+    const file = path.join(packageRoot, relative);
+    if (!(await exists(file))) { errors.push(`missing routing asset: ${relative}`); continue; }
+    const text = await readFile(file, 'utf8');
+    for (const id of text.match(/showdar-[a-z-]+/g) ?? []) if (!known.has(id)) errors.push(`${relative} references unknown skill ${id}`);
+  }
+
+  const commandMap = {
+    understand: 'showdar-understand', plan: 'showdar-plan', design: 'showdar-design', build: 'showdar-build',
+    debug: 'showdar-debug', test: 'showdar-test', review: 'showdar-review', upgrade: 'showdar-upgrade',
+    ship: 'showdar-ship', recover: 'showdar-recover', git: 'showdar-git',
+    requirements: 'showdar-requirements', quality: 'showdar-quality', security: 'showdar-security', ops: 'showdar-ops',
+  };
+  for (const [command, skill] of Object.entries(commandMap)) {
+    const relative = `commands/opencode/showdar/${command}.md`;
+    const file = path.join(packageRoot, relative);
+    if (!(await exists(file))) { errors.push(`missing OpenCode command: ${relative}`); continue; }
+    const text = await readFile(file, 'utf8');
+    if (!text.includes('$ARGUMENTS')) errors.push(`${relative} does not accept $ARGUMENTS`);
+    if (!text.includes(skill)) errors.push(`${relative} does not route to ${skill}`);
+  }
+  const skillCommand = path.join(packageRoot, 'commands', 'opencode', 'showdar', 'skill.md');
+  if (!(await exists(skillCommand))) errors.push('missing OpenCode command: commands/opencode/showdar/skill.md');
+  else {
+    const text = await readFile(skillCommand, 'utf8');
+    if (!text.includes('$ARGUMENTS')) errors.push('commands/opencode/showdar/skill.md does not accept $ARGUMENTS');
+    for (const id of known) if (!text.includes(id)) errors.push(`commands/opencode/showdar/skill.md does not list ${id}`);
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}