cdspec 0.1.0 → 0.1.3

package/src/skill-core/adapters/shared.ts

@@ -1,45 +0,0 @@
-import { copyFile, readFile, readdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { ensureDir, pathExists } from "../../utils/fs.js";
-import { SkillManifest } from "../types.js";
-
-export async function emitWithLayout(
-  manifest: SkillManifest,
-  outDir: string,
-  includeOriginalSkillMd: boolean,
-  generatedFiles: Array<{ relativePath: string; content: string }>
-): Promise<void> {
-  await ensureDir(outDir);
-  if (includeOriginalSkillMd) {
-    const srcSkillMd = path.join(manifest.sourcePath, "SKILL.md");
-    await copyFile(srcSkillMd, path.join(outDir, "SKILL.md"));
-  }
-
-  for (const file of generatedFiles) {
-    const targetFile = path.join(outDir, file.relativePath);
-    await ensureDir(path.dirname(targetFile));
-    await writeFile(targetFile, file.content, "utf8");
-  }
-
-  const folders = ["agents", "references", "scripts", "assets"];
-  for (const folder of folders) {
-    const sourceFolder = path.join(manifest.sourcePath, folder);
-    if (!(await pathExists(sourceFolder))) continue;
-    await copyFolder(sourceFolder, path.join(outDir, folder));
-  }
-}
-
-async function copyFolder(srcDir: string, dstDir: string): Promise<void> {
-  await ensureDir(dstDir);
-  const entries = await readdir(srcDir, { withFileTypes: true });
-  for (const entry of entries) {
-    const src = path.join(srcDir, entry.name);
-    const dst = path.join(dstDir, entry.name);
-    if (entry.isDirectory()) {
-      await copyFolder(src, dst);
-      continue;
-    }
-    const data = await readFile(src);
-    await writeFile(dst, data);
-  }
-}

package/src/skill-core/manifest-loader.ts

@@ -1,79 +0,0 @@
-import { readdir, readFile } from "node:fs/promises";
-import path from "node:path";
-import { parseFrontmatter } from "../utils/frontmatter.js";
-import { listDirs, pathExists } from "../utils/fs.js";
-import { SkillManifest } from "./types.js";
-
-const CODEX_DIR = ".codex";
-
-export async function loadAllSkillManifests(cwd: string): Promise<SkillManifest[]> {
-  const sourceRoot = path.join(cwd, CODEX_DIR);
-  const skillDirs = await listDirs(sourceRoot);
-  const manifests: SkillManifest[] = [];
-  for (const dirName of skillDirs) {
-    const fullPath = path.join(sourceRoot, dirName);
-    const manifest = await loadSkillManifest(fullPath);
-    if (manifest) manifests.push(manifest);
-  }
-  return manifests;
-}
-
-export async function loadSkillManifestByName(
-  cwd: string,
-  name: string
-): Promise<SkillManifest | null> {
-  return loadSkillManifest(path.join(cwd, CODEX_DIR, name));
-}
-
-async function loadSkillManifest(skillDir: string): Promise<SkillManifest | null> {
-  const skillMdPath = path.join(skillDir, "SKILL.md");
-  if (!(await pathExists(skillMdPath))) return null;
-
-  const content = await readFile(skillMdPath, "utf8");
-  const parsed = parseFrontmatter(content);
-  const frontName = parsed.attributes.name?.trim();
-  const frontDescription = parsed.attributes.description?.trim();
-  const displayName = frontName || path.basename(skillDir);
-
-  const agents = await collectRelativeFiles(path.join(skillDir, "agents"), "agents");
-  const resources = await collectRelativeFiles(path.join(skillDir, "references"), "references");
-  const scripts = await collectRelativeFiles(path.join(skillDir, "scripts"), "scripts");
-  const assets = await collectRelativeFiles(path.join(skillDir, "assets"), "assets");
-
-  return {
-    name: displayName,
-    description: frontDescription || "",
-    body: parsed.body.trim(),
-    agents,
-    resources: [...resources, ...scripts, ...assets],
-    sourcePath: skillDir
-  };
-}
-
-async function collectRelativeFiles(
-  dirPath: string,
-  prefix: string
-): Promise<string[]> {
-  if (!(await pathExists(dirPath))) return [];
-  const result: string[] = [];
-  await walk(dirPath, (absolutePath) => {
-    const relative = path.relative(path.dirname(dirPath), absolutePath);
-    result.push(relative.replaceAll("\\", "/").replace(`${prefix}/./`, `${prefix}/`));
-  });
-  return result;
-}
-
-async function walk(
-  dirPath: string,
-  onFile: (absolutePath: string) => void
-): Promise<void> {
-  const entries = await readdir(dirPath, { withFileTypes: true });
-  for (const entry of entries) {
-    const absolute = path.join(dirPath, entry.name);
-    if (entry.isDirectory()) {
-      await walk(absolute, onFile);
-      continue;
-    }
-    onFile(absolute);
-  }
-}

package/src/skill-core/scaffold.ts

@@ -1,192 +0,0 @@
-import { mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { parseFrontmatter } from "../utils/frontmatter.js";
-import { ensureDir, listDirs, pathExists } from "../utils/fs.js";
-import { SkillManifest } from "./types.js";
-
-const DEFAULT_SKILL_NAME = "openspec-core";
-const BUILTIN_TEMPLATE_DIR = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "../../templates/default-skill"
-);
-
-export async function cleanupLegacyDefaultSkillDir(cwd: string): Promise<void> {
-  await rm(path.join(cwd, ".codex", DEFAULT_SKILL_NAME), { recursive: true, force: true });
-  await rm(path.join(cwd, ".cdspec", "seed-skills"), { recursive: true, force: true });
-}
-
-export async function loadDefaultSkillManifest(cwd: string): Promise<SkillManifest> {
-  const projectTemplateManifests = await loadProjectTemplateManifests(cwd);
-  if (projectTemplateManifests.length > 0) return projectTemplateManifests[0];
-
-  if (await pathExists(path.join(BUILTIN_TEMPLATE_DIR, "SKILL.md"))) {
-    return buildManifestFromDir(BUILTIN_TEMPLATE_DIR);
-  }
-  const tempDir = await buildFallbackTemplateInTemp();
-  return buildManifestFromDir(tempDir);
-}
-
-export async function loadProjectTemplateManifests(cwd: string): Promise<SkillManifest[]> {
-  return loadFromProjectTemplates(path.join(cwd, "templates"));
-}
-
-async function buildManifestFromDir(skillDir: string): Promise<SkillManifest> {
-  const raw = await readFile(path.join(skillDir, "SKILL.md"), "utf8");
-  const parsed = parseFrontmatter(raw);
-  const name = parsed.attributes.name?.trim() || DEFAULT_SKILL_NAME;
-  const description = parsed.attributes.description?.trim() || "OpenSpec default skill";
-  const agents = await collectRelativeFiles(path.join(skillDir, "agents"));
-  const references = await collectRelativeFiles(path.join(skillDir, "references"));
-  const scripts = await collectRelativeFiles(path.join(skillDir, "scripts"));
-  const assets = await collectRelativeFiles(path.join(skillDir, "assets"));
-  return {
-    name,
-    description,
-    body: parsed.body.trim(),
-    agents,
-    resources: [...references, ...scripts, ...assets],
-    sourcePath: skillDir
-  };
-}
-
-async function collectRelativeFiles(dirPath: string): Promise<string[]> {
-  if (!(await pathExists(dirPath))) return [];
-  const base = path.dirname(dirPath);
-  const result: string[] = [];
-  const dirs = [dirPath];
-  while (dirs.length > 0) {
-    const current = dirs.pop()!;
-    const children = await listDirs(current);
-    for (const child of children) {
-      dirs.push(path.join(current, child));
-    }
-    const entries = await readdir(current, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isFile()) continue;
-      const fullPath = path.join(current, entry.name);
-      result.push(path.relative(base, fullPath).replaceAll("\\", "/"));
-    }
-  }
-  return result;
-}
-
-async function buildFallbackTemplateInTemp(): Promise<string> {
-  const root = await mkdtemp(path.join(os.tmpdir(), "cdspec-skill-"));
-  await ensureDir(path.join(root, "agents"));
-  await ensureDir(path.join(root, "references"));
-  const skillMd = [
-    "---",
-    "name: openspec-core",
-    "description: OpenSpec-style change workflow skill. Use for proposing, exploring, applying, and archiving spec-driven changes.",
-    "---",
-    "",
-    "# OpenSpec Core Skill",
-    "",
-    "1. /opsx-propose",
-    "2. /opsx-explore",
-    "3. /opsx-apply",
-    "4. /opsx-archive"
-  ].join("\n");
-  const openaiYaml = [
-    "interface:",
-    '  display_name: "OpenSpec Core"',
-    '  short_description: "Spec-driven change workflow with propose/explore/apply/archive"',
-    '  default_prompt: "Use $openspec-core to run OpenSpec-style workflows in this repository."'
-  ].join("\n");
-  await writeFile(path.join(root, "SKILL.md"), `${skillMd}\n`, "utf8");
-  await writeFile(path.join(root, "agents", "openai.yaml"), `${openaiYaml}\n`, "utf8");
-  await writeFile(path.join(root, "references", "project_notes.md"), "# OpenSpec Workflow Notes\n");
-  return root;
-}
-
-async function loadFromProjectTemplates(templateRoot: string): Promise<SkillManifest[]> {
-  if (!(await pathExists(templateRoot))) return [];
-  const manifests: SkillManifest[] = [];
-
-  const childDirs = await listDirs(templateRoot);
-  for (const child of childDirs) {
-    const full = path.join(templateRoot, child);
-    if (await pathExists(path.join(full, "SKILL.md"))) {
-      manifests.push(await buildManifestFromDir(full));
-    }
-  }
-
-  if (manifests.length > 0) return manifests;
-
-  const markdownFiles = await collectMarkdownFiles(templateRoot);
-  for (const selected of markdownFiles.sort()) {
-    manifests.push(await buildManifestFromMarkdown(templateRoot, selected));
-  }
-  return manifests;
-}
-
-async function buildManifestFromMarkdown(
-  templateRoot: string,
-  selected: string
-): Promise<SkillManifest> {
-  const raw = await readFile(selected, "utf8");
-  const parsed = parseFrontmatter(raw);
-  const baseName = path.basename(selected, path.extname(selected));
-  const skillName = normalizeSkillName(parsed.attributes.name || baseName);
-  const description =
-    parsed.attributes.description ||
-    `Generated from templates/${path.relative(templateRoot, selected).replaceAll("\\", "/")}`;
-  const body = parsed.body.trim() || raw.trim();
-
-  const tmp = await mkdtemp(path.join(os.tmpdir(), "cdspec-template-"));
-  await ensureDir(path.join(tmp, "agents"));
-  await ensureDir(path.join(tmp, "references"));
-  const skillMd = ["---", `name: ${skillName}`, `description: ${description}`, "---", "", body].join(
-    "\n"
-  );
-  const openaiYaml = [
-    "interface:",
-    `  display_name: "${humanizeName(skillName)}"`,
-    `  short_description: "${escapeYaml(description)}"`,
-    `  default_prompt: "Use $${skillName} to follow this template skill."`
-  ].join("\n");
-  await writeFile(path.join(tmp, "SKILL.md"), `${skillMd}\n`, "utf8");
-  await writeFile(path.join(tmp, "agents", "openai.yaml"), `${openaiYaml}\n`, "utf8");
-  await writeFile(path.join(tmp, "references", path.basename(selected)), raw, "utf8");
-  return buildManifestFromDir(tmp);
-}
-
-async function collectMarkdownFiles(root: string): Promise<string[]> {
-  const files: string[] = [];
-  const queue = [root];
-  while (queue.length > 0) {
-    const current = queue.pop()!;
-    const dirs = await listDirs(current);
-    for (const dir of dirs) {
-      queue.push(path.join(current, dir));
-    }
-    const entries = await readdir(current, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-        files.push(path.join(current, entry.name));
-      }
-    }
-  }
-  return files;
-}
-
-function normalizeSkillName(input: string): string {
-  return input
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "") || DEFAULT_SKILL_NAME;
-}
-
-function humanizeName(input: string): string {
-  return input
-    .split("-")
-    .filter(Boolean)
-    .map((part) => part[0].toUpperCase() + part.slice(1))
-    .join(" ");
-}
-
-function escapeYaml(value: string): string {
-  return value.replace(/"/g, '\\"');
-}

package/src/skill-core/service.ts

@@ -1,199 +0,0 @@
-import path from "node:path";
-import { rm } from "node:fs/promises";
-import { loadConfig } from "../config/loader.js";
-import { resolveAgentRoot } from "../config/path.js";
-import { CDSpecConfig } from "../config/types.js";
-import { loadAllSkillManifests, loadSkillManifestByName } from "./manifest-loader.js";
-import { expandTargets, getAdapter } from "./adapters/index.js";
-import {
-  installToolInteractionTemplates,
-  writeSharedAgentsStub
-} from "./tool-interactions.js";
-import {
-  cleanupLegacyDefaultSkillDir,
-  loadDefaultSkillManifest,
-  loadProjectTemplateManifests
-} from "./scaffold.js";
-import { SkillManifest } from "./types.js";
-import { validateManifest } from "./validator.js";
-
-export async function listSkills(cwd: string): Promise<string[]> {
-  const manifests = await loadAllSkillManifests(cwd);
-  return manifests.map((manifest) => manifest.name).sort();
-}
-
-export async function addSkill(
-  cwd: string,
-  name: string,
-  targetRaw: string,
-  force: boolean
-): Promise<void> {
-  const config = await loadConfig(cwd);
-  let manifest = await loadSkillManifestByName(cwd, name);
-  if (!manifest) {
-    const all = await loadAllSkillManifests(cwd);
-    manifest = all.find((item) => item.name === name) ?? null;
-  }
-  if (!manifest) {
-    throw new Error(`Skill "${name}" not found under .codex/.`);
-  }
-  const diagnostics = [...validateManifest(manifest)];
-  const targets = expandTargets(targetRaw);
-  for (const target of targets) {
-    diagnostics.push(...getAdapter(target).validate(manifest));
-  }
-  failIfErrors(diagnostics);
-
-  for (const target of targets) {
-    const adapter = getAdapter(target);
-    const outDir = path.join(resolveAgentRoot(cwd, config.agents[target].rootDir), "skills", manifest.name);
-    await adapter.emit(manifest, outDir, force);
-  }
-}
-
-export async function syncSkills(
-  cwd: string,
-  targetRaw: string,
-  force: boolean
-): Promise<void> {
-  const config = await loadConfig(cwd);
-  const manifests = await loadAllSkillManifests(cwd);
-  if (manifests.length === 0) {
-    throw new Error("No skills found under .codex/.");
-  }
-  const targets = expandTargets(targetRaw);
-
-  for (const manifest of manifests) {
-    const diagnostics = [...validateManifest(manifest)];
-    for (const target of targets) {
-      diagnostics.push(...getAdapter(target).validate(manifest));
-    }
-    failIfErrors(diagnostics);
-  }
-
-  for (const manifest of manifests) {
-    for (const target of targets) {
-      const outDir = path.join(resolveAgentRoot(cwd, config.agents[target].rootDir), "skills", manifest.name);
-      await getAdapter(target).emit(manifest, outDir, force);
-    }
-  }
-}
-
-export async function initSkills(
-  cwd: string,
-  agentsRaw: string,
-  force: boolean
-): Promise<string[]> {
-  await cleanupLegacyDefaultSkillDir(cwd);
-  const baseConfig = await loadConfig(cwd);
-  const projectTemplateManifests = await loadProjectTemplateManifests(cwd);
-  let manifests = projectTemplateManifests.length > 0
-    ? projectTemplateManifests
-    : await loadAllSkillManifests(cwd);
-  if (manifests.length === 0) manifests = [await loadDefaultSkillManifest(cwd)];
-  const config = buildInitConfig(baseConfig, manifests);
-  const targets = expandTargets(agentsRaw);
-  if (force) {
-    for (const target of targets) {
-      const root = resolveAgentRoot(cwd, config.agents[target].rootDir);
-      await rm(path.join(root, "skills"), {
-        recursive: true,
-        force: true
-      });
-      await rm(path.join(root, config.agents[target].commandsDir), {
-        recursive: true,
-        force: true
-      });
-      const guide = config.agents[target].guideAtProjectRoot
-        ? path.join(cwd, config.agents[target].guideFile)
-        : path.join(root, config.agents[target].guideFile);
-      await rm(guide, { force: true });
-    }
-  }
-  for (const manifest of manifests) {
-    const diagnostics = [...validateManifest(manifest)];
-    for (const target of targets) {
-      diagnostics.push(...getAdapter(target).validate(manifest));
-    }
-    failIfErrors(diagnostics);
-  }
-
-  for (const manifest of manifests) {
-    for (const target of targets) {
-      const outDir = path.join(resolveAgentRoot(cwd, config.agents[target].rootDir), "skills", manifest.name);
-      await getAdapter(target).emit(manifest, outDir, force);
-    }
-  }
-
-  const files: string[] = [];
-  for (const target of targets) {
-    files.push(...(await installToolInteractionTemplates(cwd, target, manifests, config)));
-  }
-  files.push(await writeSharedAgentsStub(cwd, targets, manifests, config));
-  return files;
-}
-
-function buildInitConfig(
-  config: CDSpecConfig,
-  manifests: SkillManifest[]
-): CDSpecConfig {
-  const available = new Set(manifests.map((item) => item.name));
-  const skillDrivenBindings = buildSkillDrivenBindings(manifests);
-  return {
-    ...config,
-    commandBindings:
-      skillDrivenBindings.length > 0
-        ? skillDrivenBindings
-        : config.commandBindings.map((item) =>
-            available.has(item.skill) ? item : { ...item, skill: manifests[0]?.name || item.skill }
-          ),
-    agents: {
-      codex: { ...config.agents.codex, commandFilePattern: "{id}.md", slashPattern: "/{id}" },
-      claudecode: {
-        ...config.agents.claudecode,
-        commandFilePattern: "{id}.md",
-        slashPattern: "/{id}"
-      },
-      iflow: { ...config.agents.iflow, commandFilePattern: "{id}.md", slashPattern: "/{id}" }
-    }
-  };
-}
-
-function buildSkillDrivenBindings(manifests: SkillManifest[]) {
-  const used = new Set<string>();
-  return manifests.map((manifest) => {
-    const base = commandIdForSkillName(manifest.name);
-    let id = base;
-    let i = 2;
-    while (used.has(id)) {
-      id = `${base}${i}`;
-      i += 1;
-    }
-    used.add(id);
-    return {
-      id,
-      skill: manifest.name,
-      description: `Run skill ${manifest.name}`
-    };
-  });
-}
-
-function commandIdForSkillName(skillName: string): string {
-  const normalizedName = skillName
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-  return `cd-${normalizedName || "skill"}`;
-}
-
-function failIfErrors(
-  diagnostics: Array<{ level: "error" | "warning"; message: string }>
-): void {
-  const warnings = diagnostics.filter((item) => item.level === "warning");
-  warnings.forEach((warning) => console.warn(`[warn] ${warning.message}`));
-
-  const errors = diagnostics.filter((item) => item.level === "error");
-  if (errors.length > 0) {
-    throw new Error(errors.map((error) => error.message).join("\n"));
-  }
-}

package/src/skill-core/tool-interactions.ts

@@ -1,95 +0,0 @@
-import { writeFile } from "node:fs/promises";
-import path from "node:path";
-import { resolveAgentRoot } from "../config/path.js";
-import { CDSpecConfig } from "../config/types.js";
-import { ensureDir } from "../utils/fs.js";
-import { SkillManifest, Target } from "./types.js";
-
-export async function installToolInteractionTemplates(
-  cwd: string,
-  target: Target,
-  skills: SkillManifest[],
-  config: CDSpecConfig
-): Promise<string[]> {
-  const agent = config.agents[target];
-  const root = resolveAgentRoot(cwd, agent.rootDir);
-  const commandsDir = path.join(root, agent.commandsDir);
-  await ensureDir(commandsDir);
-  const created: string[] = [];
-
-  for (const binding of config.commandBindings) {
-    const fileName = agent.commandFilePattern.replace("{id}", binding.id);
-    const file = path.join(commandsDir, fileName);
-    await writeFile(file, renderCommandTemplate(target, binding.id, binding.skill, binding.description), "utf8");
-    created.push(file);
-  }
-
-  const guidePath = agent.guideAtProjectRoot
-    ? path.join(cwd, agent.guideFile)
-    : path.join(root, agent.guideFile);
-  await writeFile(guidePath, renderGuide(target, skills, config), "utf8");
-  created.push(guidePath);
-  return created;
-}
-
-export async function writeSharedAgentsStub(
-  cwd: string,
-  targets: Target[],
-  skills: SkillManifest[],
-  config: CDSpecConfig
-): Promise<string> {
-  const file = path.join(cwd, "AGENTS.md");
-  const lines = [
-    "# AGENTS instructions",
-    "",
-    "<INSTRUCTIONS>",
-    "## OpenSpec Setup",
-    `Enabled targets: ${targets.join(", ")}`,
-    "### Skills",
-    ...skills.map((skill) => `- ${skill.name}: ${skill.description || "No description"}`),
-    "### Command Bindings",
-    ...config.commandBindings.map((binding) => `- ${binding.id} -> ${binding.skill}`),
-    "</INSTRUCTIONS>",
-    ""
-  ];
-  await writeFile(file, lines.join("\n"), "utf8");
-  return file;
-}
-
-function renderCommandTemplate(
-  target: Target,
-  commandId: string,
-  skillName: string,
-  description: string
-): string {
-  return [
-    `# ${commandId} (${target})`,
-    "",
-    description,
-    "",
-    "## Skill binding",
-    `- skill: ${skillName}`,
-    "",
-    "## Required output",
-    "- Change ID",
-    "- Updated files",
-    "- Validation summary"
-  ].join("\n");
-}
-
-function renderGuide(target: Target, skills: SkillManifest[], config: CDSpecConfig): string {
-  const agent = config.agents[target];
-  const commandList = config.commandBindings.map((binding) =>
-    `- ${agent.slashPattern.replace("{id}", binding.id)} -> ${binding.skill}`
-  );
-  return [
-    `# ${target} OpenSpec-style setup`,
-    "",
-    "## Installed skills",
-    ...skills.map((skill) => `- ${skill.name}: ${skill.description || "No description"}`),
-    "",
-    "## Commands",
-    ...commandList,
-    ""
-  ].join("\n");
-}

package/src/skill-core/types.ts

@@ -1,22 +0,0 @@
-export type Target = "codex" | "claudecode" | "iflow";
-
-export interface SkillManifest {
-  name: string;
-  description: string;
-  body: string;
-  agents: string[];
-  resources: string[];
-  sourcePath: string;
-}
-
-export interface Diagnostic {
-  level: "error" | "warning";
-  message: string;
-}
-
-export interface TargetAdapter {
-  target: Target;
-  validate(manifest: SkillManifest): Diagnostic[];
-  emit(manifest: SkillManifest, outDir: string, force: boolean): Promise<void>;
-}
-

package/src/skill-core/validator.ts

@@ -1,28 +0,0 @@
-import { Diagnostic, SkillManifest } from "./types.js";
-
-export function validateManifest(manifest: SkillManifest): Diagnostic[] {
-  const diagnostics: Diagnostic[] = [];
-  if (!manifest.name) {
-    diagnostics.push({ level: "error", message: "Skill name is required." });
-  }
-  if (!manifest.description) {
-    diagnostics.push({
-      level: "error",
-      message: `Skill "${manifest.name}" is missing frontmatter description.`
-    });
-  }
-  if (!manifest.body) {
-    diagnostics.push({
-      level: "warning",
-      message: `Skill "${manifest.name}" has empty SKILL.md body.`
-    });
-  }
-  if (!/^[a-z0-9-]+$/.test(manifest.name)) {
-    diagnostics.push({
-      level: "warning",
-      message: `Skill "${manifest.name}" should use lowercase letters, numbers, and hyphens.`
-    });
-  }
-  return diagnostics;
-}
-