@superdoc-dev/sdk 1.0.0-alpha.1 → 1.0.0-alpha.3

package/src/skills.ts

@@ -1,10 +1,34 @@
-import { readFileSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { SuperDocCliError } from './runtime/errors';
 
 const skillsDir = path.resolve(fileURLToPath(new URL('../skills', import.meta.url)));
 const SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SUPPORTED_SKILL_RUNTIMES = ['claude'] as const;
+const SUPPORTED_INSTALL_SCOPES = ['project', 'user'] as const;
+
+type SkillRuntime = (typeof SUPPORTED_SKILL_RUNTIMES)[number];
+type SkillInstallScope = (typeof SUPPORTED_INSTALL_SCOPES)[number];
+
+export interface InstallSkillOptions {
+  runtime?: SkillRuntime;
+  scope?: SkillInstallScope;
+  targetDir?: string;
+  cwd?: string;
+  homeDir?: string;
+  overwrite?: boolean;
+}
+
+export interface InstalledSkillResult {
+  name: string;
+  runtime: SkillRuntime;
+  scope: SkillInstallScope | 'custom';
+  path: string;
+  written: boolean;
+  overwritten: boolean;
+}
 
 function resolveSkillFilePath(skillName: string): string {
   const filePath = path.resolve(skillsDir, `${skillName}.md`);
@@ -18,6 +42,23 @@ function resolveSkillFilePath(skillName: string): string {
   return filePath;
 }
 
+function normalizeSkillName(name: string): string {
+  const normalized = name.trim();
+  if (!normalized || !SKILL_NAME_RE.test(normalized)) {
+    throw new SuperDocCliError('Skill name is required.', {
+      code: 'INVALID_ARGUMENT',
+      details: { name },
+    });
+  }
+  return normalized;
+}
+
+/**
+ * List the names of all SDK skills bundled with this package.
+ *
+ * @returns Sorted array of skill names (without the `.md` extension).
+ * @throws {SuperDocCliError} With code `SKILL_IO_ERROR` if the skills directory cannot be read.
+ */
 export function listSkills(): string[] {
   try {
     return readdirSync(skillsDir)
@@ -35,14 +76,17 @@ export function listSkills(): string[] {
   }
 }
 
+/**
+ * Read the content of a bundled SDK skill by name.
+ *
+ * @param name - Skill name (e.g. `"editing-docx"`). Must match `[A-Za-z0-9][A-Za-z0-9_-]*`.
+ * @returns The skill file content as a UTF-8 string.
+ * @throws {SuperDocCliError} With code `INVALID_ARGUMENT` if the name is empty or contains invalid characters.
+ * @throws {SuperDocCliError} With code `SKILL_NOT_FOUND` if no skill with that name exists.
+ * @throws {SuperDocCliError} With code `SKILL_IO_ERROR` for other file-system read failures.
+ */
 export function getSkill(name: string): string {
-  const normalized = name.trim();
-  if (!normalized || !SKILL_NAME_RE.test(normalized)) {
-    throw new SuperDocCliError('Skill name is required.', {
-      code: 'INVALID_ARGUMENT',
-      details: { name },
-    });
-  }
+  const normalized = normalizeSkillName(name);
 
   const filePath = resolveSkillFilePath(normalized);
   try {
@@ -74,3 +118,78 @@ export function getSkill(name: string): string {
     });
   }
 }
+
+/**
+ * Install a bundled SDK skill into an agent runtime directory.
+ *
+ * Defaults to Claude's project-local skill path: `./.claude/skills/<name>/SKILL.md`.
+ */
+export function installSkill(name: string, options: InstallSkillOptions = {}): InstalledSkillResult {
+  const normalizedName = normalizeSkillName(name);
+  const runtime = options.runtime ?? 'claude';
+  if (!SUPPORTED_SKILL_RUNTIMES.includes(runtime)) {
+    throw new SuperDocCliError('Unsupported skill runtime.', {
+      code: 'INVALID_ARGUMENT',
+      details: { runtime, supportedRuntimes: SUPPORTED_SKILL_RUNTIMES },
+    });
+  }
+
+  const scope = options.scope ?? 'project';
+  if (!SUPPORTED_INSTALL_SCOPES.includes(scope)) {
+    throw new SuperDocCliError('Unsupported skill install scope.', {
+      code: 'INVALID_ARGUMENT',
+      details: { scope, supportedScopes: SUPPORTED_INSTALL_SCOPES },
+    });
+  }
+
+  const skillsRoot =
+    options.targetDir !== undefined
+      ? path.resolve(options.targetDir)
+      : scope === 'user'
+        ? path.resolve(options.homeDir ?? os.homedir(), '.claude', 'skills')
+        : path.resolve(options.cwd ?? process.cwd(), '.claude', 'skills');
+  const skillFile = path.join(skillsRoot, normalizedName, 'SKILL.md');
+  const overwrite = options.overwrite ?? true;
+  const alreadyExists = existsSync(skillFile);
+
+  if (!overwrite && alreadyExists) {
+    return {
+      name: normalizedName,
+      runtime,
+      scope: options.targetDir !== undefined ? 'custom' : scope,
+      path: skillFile,
+      written: false,
+      overwritten: false,
+    };
+  }
+
+  try {
+    const content = getSkill(name);
+    mkdirSync(path.dirname(skillFile), { recursive: true });
+    writeFileSync(skillFile, content, 'utf8');
+  } catch (error) {
+    if (error instanceof SuperDocCliError) {
+      throw error;
+    }
+
+    throw new SuperDocCliError('Unable to install SDK skill.', {
+      code: 'SKILL_IO_ERROR',
+      details: {
+        name: normalizedName,
+        runtime,
+        scope: options.targetDir !== undefined ? 'custom' : scope,
+        path: skillFile,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+
+  return {
+    name: normalizedName,
+    runtime,
+    scope: options.targetDir !== undefined ? 'custom' : scope,
+    path: skillFile,
+    written: true,
+    overwritten: alreadyExists,
+  };
+}