@birdapi/velinstyle 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@birdapi/velinstyle",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -27,7 +27,8 @@
     "./attributes": "./core/attributes/index.js",
     "./highlight": "./core/highlight/index.js",
     "./meta": "./core/meta/index.js",
-    "./a11y": "./components/a11y-entry.js"
+    "./a11y": "./components/a11y-entry.js",
+    "./skills-registry": "./packages/velinstyle-skills/registry.json"
   },
   "bin": {
     "velinstyle": "cli/index.js"
@@ -46,6 +47,9 @@
     "components/",
     "core/",
     "cli/",
+    "packages/skill-engine/",
+    "packages/velinstyle-skills/",
+    "schemas/",
     "examples/search-index.schema.json",
     "icons/velin-icons.svg"
   ],
@@ -80,18 +84,28 @@
     "tokens:validate:full": "node cli/index.js tokens validate --input examples/tokens.full.json",
     "docs:generate": "node cli/index.js docs generate",
     "search:index": "node cli/index.js search index",
+    "skills:generate": "node packages/velinstyle-skills/scripts/generate-assets.mjs && node -e \"import('./packages/velinstyle-skills/index.js').then(m=>m.writeCatalogFile())\"",
+    "skills:validate": "node scripts/validate-skills.mjs",
+    "skills:doctor": "node scripts/check-skills-paths.mjs",
     "meta:build": "node cli/index.js meta",
     "ci:checks": "node scripts/ci-checks.mjs",
+    "check:blueprints": "node scripts/check-blueprint-classes.mjs",
+    "check:chaos": "node scripts/check-chaos-detection.mjs",
     "release:check": "node scripts/check-release-sync.mjs",
     "release:sync": "node scripts/check-release-sync.mjs --fix",
-    "prepublishOnly": "npm run build && npm run search:index && npm run meta:build && npm run release:check -- --skip-site",
+    "intelligence:validate": "node scripts/validate-intelligence-schemas.mjs",
+    "prepublishOnly": "npm run build && npm run check:blueprints && npm run search:index && npm run skills:generate && npm run skills:validate && npm run skills:doctor && npm run meta:build && npm run intelligence:validate && npm run release:check -- --skip-site",
     "pack:check": "npm pack --dry-run",
     "docs:prepare": "npm run build && node scripts/prepare-docs-pages.js",
     "docs:patch-nav": "node scripts/patch-docs-nav.js",
     "docs:sync-site": "npm run build && npm run docs:generate && python ../velinstyle-site/tools/sync-framework-0.9.0.py && python ../velinstyle-site/tools/patch-site-a11y-aaa.py && python ../velinstyle-site/tools/patch-docs-090-final.py",
     "readme:capture": "node tools/capture-readme-demos.mjs",
     "readme:assets:webp": "node tools/readme-png-to-webp.mjs",
-    "demos:sync": "node tools/sync-demos-to-repo.mjs --out showcase-demos && node tools/sync-demos-to-repo.mjs --out ../velinstyle-demos"
+    "demos:sync": "node tools/sync-demos-to-repo.mjs --out showcase-demos && node tools/sync-demos-to-repo.mjs --out ../velinstyle-demos",
+    "strategy:bootstrap-issues": "node scripts/bootstrap-github-backlog.mjs",
+    "strategy:bootstrap-issues:dry": "node scripts/bootstrap-github-backlog.mjs --dry-run",
+    "strategy:bootstrap-next30": "node scripts/bootstrap-github-backlog.mjs --issues-only --seed=../interne_docs/strategy/next-30-issues.json --map=../interne_docs/strategy/next-30-issue-map.json",
+    "strategy:bootstrap-next30:dry": "node scripts/bootstrap-github-backlog.mjs --dry-run --issues-only --seed=../interne_docs/strategy/next-30-issues.json --map=../interne_docs/strategy/next-30-issue-map.json"
   },
   "keywords": [
     "css",
@@ -110,11 +124,11 @@
   "author": "SkyliteDesign",
   "license": "MIT",
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "axe-core": "^4.10.0",
     "esbuild": "^0.24.0",
     "jsdom": "^26.1.0",
     "lightningcss-cli": "^1.28.0",
-    "@playwright/test": "^1.60.0",
     "playwright": "^1.60.0",
     "serve": "^14.0.0",
     "sharp": "^0.34.5",
@@ -123,6 +137,6 @@
     "vitest": "^3.2.0"
   },
   "dependencies": {
-    "isomorphic-dompurify": "^3.13.0"
+    "isomorphic-dompurify": "^3.21.0"
   }
 }

package/packages/skill-engine/README.md

@@ -0,0 +1,24 @@
+# `@velinstyle/skill-engine`
+
+Internal runtime helpers for VelinStyle **AI Skills** (registry resolution, workflow graphs, install/run orchestration).
+
+**Consumers:** `packages/velinstyle-skills` and the `velinstyle skills` / `workflow` CLI.
+
+**Status:** Foundation / beta — not a standalone public product API yet.
+
+## Docs
+
+- Beginner: [`../../docs/guides/ai-skills.md`](../../docs/guides/ai-skills.md)
+- Strategy: [`../../../interne_docs/strategy/AI_SKILLS.md`](../../../interne_docs/strategy/AI_SKILLS.md) (local monorepo)
+- Architecture: [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md)
+
+## Usage
+
+Prefer the CLI:
+
+```bash
+velinstyle skills list
+velinstyle workflow landingpage --json
+```
+
+Direct imports are for framework tooling and advanced integrations — expect breaking changes until skills leave Foundation.

package/packages/skill-engine/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@birdapi/skill-engine",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js"
+}

package/packages/skill-engine/src/catalog.js

@@ -0,0 +1,29 @@
+export function buildCatalogProjection(registry) {
+  return {
+    version: registry.version,
+    generatedAt: new Date().toISOString(),
+    totals: {
+      skills: (registry.skills || []).length,
+      packs: (registry.packs || []).length,
+      workflowGraphs: (registry.workflowGraphs || []).length,
+      bundles: (registry.bundles || []).length,
+      templates: (registry.templates || []).length,
+      projects: (registry.projects || []).length,
+    },
+    skills: (registry.skills || []).map((skill) => ({
+      id: skill.id,
+      name: skill.name || skill.id,
+      category: skill.category,
+      priority: skill.priority,
+      status: skill.status,
+      confidence: skill.confidence,
+      capabilities: skill.capabilities || [],
+      description: skill.description || '',
+    })),
+    packs: registry.packs || [],
+    workflowGraphs: (registry.workflowGraphs || []).map((item) => ({ id: item.id, name: item.name, entry: item.entry })),
+    bundles: registry.bundles || [],
+    templates: registry.templates || [],
+    projects: registry.projects || [],
+  };
+}

package/packages/skill-engine/src/index.js

@@ -0,0 +1,5 @@
+export { loadRegistry, listSkills, findSkillById } from './registry.js';
+export { resolveSkillGraph, resolveWorkflowGraph } from './resolve.js';
+export { validateRegistry } from './validate.js';
+export { buildCatalogProjection } from './catalog.js';
+export { installSelection } from './install.js';

package/packages/skill-engine/src/install.js

@@ -0,0 +1,69 @@
+import { cpSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { findSkillById } from './registry.js';
+import { resolveSkillGraph, resolveWorkflowGraph } from './resolve.js';
+
+function ensureDir(path) {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+}
+
+function copySkillFromRegistry(registry, skillsRoot, targetRoot, skillId) {
+  const skill = findSkillById(registry, skillId);
+  if (!skill || !skill.prosePath) return false;
+  const prosePath = join(skillsRoot, skill.prosePath);
+  const targetDir = join(targetRoot, skillId);
+  ensureDir(targetDir);
+  cpSync(prosePath, join(targetDir, 'SKILL.md'));
+  return true;
+}
+
+export function installSelection(registry, options) {
+  const { selection, skillsRoot, targetRoot, includeDependencies = true } = options;
+  ensureDir(targetRoot);
+  const installed = [];
+  const issues = [];
+
+  const addSkill = (skillId) => {
+    if (installed.includes(skillId)) return;
+    if (includeDependencies) {
+      const resolved = resolveSkillGraph(registry, skillId);
+      issues.push(...resolved.issues);
+      for (const dep of resolved.orderedSkillIds) {
+        if (copySkillFromRegistry(registry, skillsRoot, targetRoot, dep)) installed.push(dep);
+      }
+      return;
+    }
+    if (copySkillFromRegistry(registry, skillsRoot, targetRoot, skillId)) installed.push(skillId);
+  };
+
+  if (selection.startsWith('bundle:')) {
+    const bundleId = selection.replace('bundle:', '');
+    const bundle = (registry.bundles || []).find((item) => item.id === bundleId);
+    if (!bundle) issues.push(`Unknown bundle ${bundleId}`);
+    for (const packId of bundle?.packs || []) {
+      const pack = (registry.packs || []).find((item) => item.id === packId);
+      for (const skillId of pack?.skills || []) addSkill(skillId);
+    }
+  } else if (selection.startsWith('project:')) {
+    const projectId = selection.replace('project:', '');
+    const project = (registry.projects || []).find((item) => item.id === projectId);
+    if (!project) issues.push(`Unknown project ${projectId}`);
+    for (const skillId of project?.skills || []) addSkill(skillId);
+    if (project?.workflowGraph) {
+      const resolved = resolveWorkflowGraph(registry, project.workflowGraph);
+      issues.push(...resolved.issues);
+      for (const skillId of resolved.orderedSteps) addSkill(skillId);
+    }
+  } else {
+    const pack = (registry.packs || []).find((item) => item.id === selection);
+    if (pack) {
+      for (const skillId of pack.skills || []) addSkill(skillId);
+    } else {
+      addSkill(selection);
+    }
+  }
+
+  const indexPath = join(targetRoot, 'README.md');
+  ensureDir(dirname(indexPath));
+  return { installed, issues };
+}

package/packages/skill-engine/src/registry.js

@@ -0,0 +1,27 @@
+import { readFileSync } from 'fs';
+
+export function loadRegistry(registryPath) {
+  return JSON.parse(readFileSync(registryPath, 'utf-8'));
+}
+
+export function listSkills(registry, filters = {}) {
+  const {
+    capability,
+    status,
+    priority,
+    origin,
+    category,
+  } = filters;
+  return (registry.skills || []).filter((skill) => {
+    if (capability && !(skill.capabilities || []).includes(capability)) return false;
+    if (status && skill.status !== status) return false;
+    if (priority && skill.priority !== priority) return false;
+    if (origin && skill.origin !== origin) return false;
+    if (category && skill.category !== category) return false;
+    return true;
+  });
+}
+
+export function findSkillById(registry, skillId) {
+  return (registry.skills || []).find((skill) => skill.id === skillId) || null;
+}

package/packages/skill-engine/src/resolve.js

@@ -0,0 +1,68 @@
+import { findSkillById } from './registry.js';
+
+function visitSkill(registry, skillId, visiting, visited, ordered, issues) {
+  if (visited.has(skillId)) return;
+  if (visiting.has(skillId)) {
+    issues.push(`Dependency cycle detected at ${skillId}`);
+    return;
+  }
+  const skill = findSkillById(registry, skillId);
+  if (!skill) {
+    issues.push(`Unknown skill reference: ${skillId}`);
+    return;
+  }
+  visiting.add(skillId);
+  for (const dep of skill.dependsOn || []) visitSkill(registry, dep, visiting, visited, ordered, issues);
+  visiting.delete(skillId);
+  visited.add(skillId);
+  ordered.push(skillId);
+}
+
+export function resolveSkillGraph(registry, skillId) {
+  const issues = [];
+  const ordered = [];
+  visitSkill(registry, skillId, new Set(), new Set(), ordered, issues);
+  return { orderedSkillIds: ordered, issues };
+}
+
+export function resolveWorkflowGraph(registry, workflowId) {
+  const graph = (registry.workflowGraphs || []).find((item) => item.id === workflowId);
+  if (!graph) return { orderedSteps: [], issues: [`Unknown workflow graph: ${workflowId}`] };
+  const nodeMap = new Map(Object.entries(graph.nodes || {}));
+  const inDegree = new Map();
+  for (const [nodeId] of nodeMap.entries()) inDegree.set(nodeId, 0);
+  for (const edge of graph.edges || []) {
+    if (!inDegree.has(edge.from) || !inDegree.has(edge.to)) {
+      return { orderedSteps: [], issues: [`Invalid edge ${edge.from} -> ${edge.to}`] };
+    }
+    inDegree.set(edge.to, (inDegree.get(edge.to) || 0) + 1);
+  }
+  const queue = [];
+  for (const [nodeId, deg] of inDegree.entries()) if (deg === 0) queue.push(nodeId);
+  const orderedNodes = [];
+  while (queue.length) {
+    const nodeId = queue.shift();
+    orderedNodes.push(nodeId);
+    for (const edge of graph.edges || []) {
+      if (edge.from !== nodeId) continue;
+      const next = (inDegree.get(edge.to) || 0) - 1;
+      inDegree.set(edge.to, next);
+      if (next === 0) queue.push(edge.to);
+    }
+  }
+  if (orderedNodes.length !== nodeMap.size) {
+    return { orderedSteps: [], issues: [`Workflow graph has a cycle: ${workflowId}`] };
+  }
+  const orderedSteps = [];
+  const issues = [];
+  for (const nodeId of orderedNodes) {
+    const node = nodeMap.get(nodeId);
+    if (!node?.skill) continue;
+    const resolved = resolveSkillGraph(registry, node.skill);
+    issues.push(...resolved.issues);
+    for (const depSkill of resolved.orderedSkillIds) {
+      if (!orderedSteps.includes(depSkill)) orderedSteps.push(depSkill);
+    }
+  }
+  return { orderedSteps, issues };
+}

package/packages/skill-engine/src/validate.js

@@ -0,0 +1,40 @@
+import { findSkillById } from './registry.js';
+import { resolveWorkflowGraph } from './resolve.js';
+
+const allowedPriority = new Set(['core', 'recommended', 'advanced', 'experimental']);
+const allowedStatus = new Set(['draft', 'experimental', 'beta', 'stable', 'deprecated', 'legacy']);
+
+export function validateRegistry(registry) {
+  const errors = [];
+  const warnings = [];
+  const ids = new Set();
+  for (const skill of registry.skills || []) {
+    if (!skill.id) errors.push('Skill without id');
+    if (ids.has(skill.id)) errors.push(`Duplicate skill id: ${skill.id}`);
+    ids.add(skill.id);
+    if (!allowedPriority.has(skill.priority)) errors.push(`Invalid priority for ${skill.id}`);
+    if (!allowedStatus.has(skill.status)) errors.push(`Invalid status for ${skill.id}`);
+    for (const dep of skill.dependsOn || []) {
+      if (!findSkillById(registry, dep)) errors.push(`Unknown dependency ${dep} in ${skill.id}`);
+    }
+  }
+
+  for (const wf of registry.workflowGraphs || []) {
+    const resolved = resolveWorkflowGraph(registry, wf.id);
+    errors.push(...resolved.issues);
+  }
+
+  for (const pack of registry.packs || []) {
+    for (const skillId of pack.skills || []) {
+      if (!findSkillById(registry, skillId)) errors.push(`Pack ${pack.id} references unknown skill ${skillId}`);
+    }
+  }
+
+  for (const project of registry.projects || []) {
+    if (project.workflowGraph && !(registry.workflowGraphs || []).some((wf) => wf.id === project.workflowGraph)) {
+      errors.push(`Project ${project.id} references unknown workflow graph ${project.workflowGraph}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}

package/packages/velinstyle-skills/README.md

@@ -0,0 +1,6 @@
+# VelinStyle Skills Registry
+
+Registry-first skill assets for AI Runtime + Skill Engine.
+
+- Source of truth: `registry.json`
+- Derived: `catalog.json`, `skills/**/SKILL.md`, `packs/*.yaml`, `graphs/*.yaml`, `bundles/*.yaml`, `templates/*.yaml`, `projects/*.yaml`

package/packages/velinstyle-skills/adapter.json

@@ -0,0 +1,8 @@
+{
+  "id": "velinstyle",
+  "name": "VelinStyle Adapter",
+  "frameworkPackage": "@birdapi/velinstyle",
+  "registryFile": "registry.json",
+  "catalogFile": "catalog.json",
+  "description": "Bridges the shared skill engine to VelinStyle CLI and meta surfaces."
+}

package/packages/velinstyle-skills/bundles/landing-starter.bundle.yaml

@@ -0,0 +1,12 @@
+id: landing-starter
+origin: official
+packs:
+  - frontend
+  - design
+  - review
+graphs:
+  - landingpage
+templates:
+  - landing-page
+docs:
+  - docs/guides/ai-skills.html

package/packages/velinstyle-skills/bundles/review-suite.bundle.yaml

@@ -0,0 +1,11 @@
+id: review-suite
+origin: official
+packs:
+  - accessibility
+  - review
+graphs:
+  - release-gate
+templates:
+
+docs:
+  - docs/guides/ai-skills.html