@compilr-dev/sdk 0.10.1 → 0.10.2

package/dist/index.d.ts

@@ -67,8 +67,8 @@ export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from '
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig, ImageToolsConfig, ImageResizer } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
-export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, } from './skills/index.js';
-export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, } from './skills/index.js';
+export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
+export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, } from './skills/index.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './skills/index.js';
 export { ACTION_REGISTRY, getActionsForContext, getActionById, resolveActionPrompt, buildContextSummary, getSuggestedRole, } from './actions/index.js';
 export type { ActionContext, ActionDefinition } from './actions/index.js';

package/dist/index.js

@@ -152,7 +152,7 @@ export { createPlatformTools, createProjectTools, createWorkItemTools, createDoc
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
-export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, } from './skills/index.js';
+export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, } from './skills/index.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './skills/index.js';
 // =============================================================================
 // Contextual Actions (skill invocations with context)

package/dist/skills/index.d.ts

@@ -6,4 +6,6 @@ export { RESERVED_SKILL_NAMES, isReservedSkillName } from './types.js';
 export { parseSkillMarkdown, loadSkillsFromDir } from './loader.js';
 export type { SkillEligibilityContext } from './resolver.js';
 export { resolveLayeredSkills, resolveSkillsForAgent } from './resolver.js';
+export type { SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './operations.js';
+export { detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill, } from './operations.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './platform-skills.js';

package/dist/skills/index.js

@@ -1,4 +1,5 @@
 export { RESERVED_SKILL_NAMES, isReservedSkillName } from './types.js';
 export { parseSkillMarkdown, loadSkillsFromDir } from './loader.js';
 export { resolveLayeredSkills, resolveSkillsForAgent } from './resolver.js';
+export { detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill, } from './operations.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './platform-skills.js';

package/dist/skills/operations.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Skill operations — reusable logic for CLI and Desktop.
+ *
+ * - Collision detection (user skills vs SDK reserved names)
+ * - Diff (fork vs upstream SDK version)
+ * - Fork scaffold (build SKILL.md with forkedFrom marker)
+ * - Validation (quality checks beyond parseSkillMarkdown)
+ * - Binding resolution (config.json slash command remapping)
+ */
+import type { CustomSkill, ForkedFromMarker } from './types.js';
+export interface SkillCollision {
+    /** The colliding skill name */
+    name: string;
+    /** Path to the user's skill folder */
+    userPath: string;
+    /** Scope where the user skill lives */
+    scope: 'user' | 'project';
+    /** SDK package that owns the reserved name */
+    sdkSource: string;
+}
+/**
+ * Detect user/project skills that shadow SDK reserved names.
+ * Called at startup to warn users about collisions introduced by SDK updates.
+ *
+ * Note: Phase 1 blocks creation of reserved names via `/skill new`, but
+ * collisions can still happen if the SDK adds new skills after the user
+ * already has a skill with that name.
+ */
+export declare function detectCollisions(userSkills: {
+    name: string;
+    scope: 'user' | 'project';
+    path: string;
+}[]): SkillCollision[];
+/**
+ * Format collision warnings for display.
+ */
+export declare function formatCollisionWarnings(collisions: SkillCollision[]): string;
+export interface SkillDiffLine {
+    type: 'same' | 'added' | 'removed';
+    content: string;
+}
+/**
+ * Compute a simple line-by-line diff between a forked skill and the
+ * upstream SDK skill it was forked from.
+ *
+ * Returns null if the upstream skill is not found.
+ */
+export declare function diffForkVsUpstream(forkPrompt: string, upstreamSkillName: string): SkillDiffLine[] | null;
+/**
+ * Build the SKILL.md content for a forked SDK skill.
+ */
+export declare function buildForkContent(sdkSkill: {
+    name: string;
+    description: string;
+    prompt: string;
+}, newName: string, sdkVersion: string): string;
+/**
+ * Build the SKILL.md template for a new custom skill.
+ */
+export declare function buildNewSkillContent(name: string, scope: string): string;
+export interface SkillValidationIssue {
+    level: 'error' | 'warning';
+    message: string;
+}
+/**
+ * Validate a parsed custom skill beyond basic frontmatter parsing.
+ */
+export declare function validateSkill(skill: CustomSkill, folderName: string): SkillValidationIssue[];
+export interface ScopeConfig {
+    slashCommands?: Record<string, string>;
+}
+export interface SkillResolution {
+    /** The resolved skill prompt */
+    prompt: string;
+    /** Original command name the user typed */
+    commandName: string;
+    /** Actual skill name that provided the prompt (may differ if bound) */
+    skillName: string;
+    /** Whether this was resolved via a binding */
+    isBound: boolean;
+    /** Fork info if the skill is forked */
+    forkedFrom?: ForkedFromMarker;
+    /** Source layer */
+    source?: CustomSkill['source'];
+}

package/dist/skills/operations.js

@@ -0,0 +1,210 @@
+/**
+ * Skill operations — reusable logic for CLI and Desktop.
+ *
+ * - Collision detection (user skills vs SDK reserved names)
+ * - Diff (fork vs upstream SDK version)
+ * - Fork scaffold (build SKILL.md with forkedFrom marker)
+ * - Validation (quality checks beyond parseSkillMarkdown)
+ * - Binding resolution (config.json slash command remapping)
+ */
+import { RESERVED_SKILL_NAMES } from './types.js';
+import { platformSkills } from './platform-skills.js';
+/**
+ * Detect user/project skills that shadow SDK reserved names.
+ * Called at startup to warn users about collisions introduced by SDK updates.
+ *
+ * Note: Phase 1 blocks creation of reserved names via `/skill new`, but
+ * collisions can still happen if the SDK adds new skills after the user
+ * already has a skill with that name.
+ */
+export function detectCollisions(userSkills) {
+    const reserved = new Set(RESERVED_SKILL_NAMES);
+    const collisions = [];
+    for (const skill of userSkills) {
+        if (reserved.has(skill.name)) {
+            collisions.push({
+                name: skill.name,
+                userPath: skill.path,
+                scope: skill.scope,
+                sdkSource: '@compilr-dev/sdk',
+            });
+        }
+    }
+    return collisions;
+}
+/**
+ * Format collision warnings for display.
+ */
+export function formatCollisionWarnings(collisions) {
+    if (collisions.length === 0)
+        return '';
+    const lines = [`⚠️  SDK update introduced new skills that collide with yours:`];
+    for (const c of collisions) {
+        lines.push(`    '${c.name}'  — your version: ${c.userPath}  (${c.scope} scope)`, `              SDK version: ${c.sdkSource}`);
+    }
+    lines.push('', '   Run /skill to view details.', '   Options: rename your skill, delete it, or fork the SDK version.');
+    return lines.join('\n');
+}
+/**
+ * Compute a simple line-by-line diff between a forked skill and the
+ * upstream SDK skill it was forked from.
+ *
+ * Returns null if the upstream skill is not found.
+ */
+export function diffForkVsUpstream(forkPrompt, upstreamSkillName) {
+    // Find the upstream SDK skill
+    // Check all platform skills + builtins
+    const allSdk = [...platformSkills];
+    const upstream = allSdk.find((s) => s.name === upstreamSkillName);
+    if (!upstream)
+        return null;
+    const upstreamLines = upstream.prompt.split('\n');
+    const forkLines = forkPrompt.split('\n');
+    return computeLineDiff(upstreamLines, forkLines);
+}
+/**
+ * Simple line diff (not a full Myers diff — sufficient for skill comparison).
+ * Uses longest common subsequence for reasonable output.
+ */
+function computeLineDiff(oldLines, newLines) {
+    const result = [];
+    let oi = 0;
+    let ni = 0;
+    while (oi < oldLines.length && ni < newLines.length) {
+        if (oldLines[oi] === newLines[ni]) {
+            result.push({ type: 'same', content: oldLines[oi] });
+            oi++;
+            ni++;
+        }
+        else {
+            // Look ahead for the next matching line
+            const matchInNew = newLines.indexOf(oldLines[oi], ni);
+            const matchInOld = oldLines.indexOf(newLines[ni], oi);
+            if (matchInNew >= 0 && (matchInOld < 0 || matchInNew - ni <= matchInOld - oi)) {
+                // Lines added in new
+                while (ni < matchInNew) {
+                    result.push({ type: 'added', content: newLines[ni] });
+                    ni++;
+                }
+            }
+            else if (matchInOld >= 0) {
+                // Lines removed from old
+                while (oi < matchInOld) {
+                    result.push({ type: 'removed', content: oldLines[oi] });
+                    oi++;
+                }
+            }
+            else {
+                // No match found — treat as replace
+                result.push({ type: 'removed', content: oldLines[oi] });
+                result.push({ type: 'added', content: newLines[ni] });
+                oi++;
+                ni++;
+            }
+        }
+    }
+    // Remaining old lines
+    while (oi < oldLines.length) {
+        result.push({ type: 'removed', content: oldLines[oi] });
+        oi++;
+    }
+    // Remaining new lines
+    while (ni < newLines.length) {
+        result.push({ type: 'added', content: newLines[ni] });
+        ni++;
+    }
+    return result;
+}
+// =============================================================================
+// Fork Scaffold
+// =============================================================================
+/**
+ * Build the SKILL.md content for a forked SDK skill.
+ */
+export function buildForkContent(sdkSkill, newName, sdkVersion) {
+    const forkedFrom = {
+        source: '@compilr-dev/sdk',
+        skill: sdkSkill.name,
+        version: sdkVersion,
+        forkedAt: new Date().toISOString(),
+    };
+    const descLines = sdkSkill.description
+        .split('\n')
+        .map((l) => `  ${l}`)
+        .join('\n');
+    const fmLines = [
+        `name: ${newName}`,
+        'description: |',
+        descLines,
+        'version: 0.1.0',
+        'forkedFrom:',
+        `  source: "${forkedFrom.source}"`,
+        `  skill: "${forkedFrom.skill}"`,
+        `  version: "${forkedFrom.version}"`,
+        `  forkedAt: "${forkedFrom.forkedAt}"`,
+    ];
+    return ['---', ...fmLines, '---', '', sdkSkill.prompt].join('\n');
+}
+// =============================================================================
+// New Skill Scaffold
+// =============================================================================
+/**
+ * Build the SKILL.md template for a new custom skill.
+ */
+export function buildNewSkillContent(name, scope) {
+    return `---
+name: ${name}
+description: |
+  Use this skill when … (replace with a paragraph-long description that names
+  the trigger conditions, the kinds of phrases the user will say, and the
+  expected output. Anthropic-style descriptions are keyword-dense and
+  intent-rich because the model reads them to decide when to load the skill.)
+version: 0.1.0
+
+# Optional — compilr extensions (ignored by Anthropic-compatible runtimes).
+# Uncomment and edit to limit which agents and project types this skill applies to.
+# compilr:
+#   targets:
+#     roles: [arch, qa]
+#   requires:
+#     tools: []
+#     projectTypes: []
+#   scope: ${scope}
+---
+
+# ${name}
+
+(Body markdown — the prompt the agent will receive when this skill activates.)
+
+## Step 1
+Describe the first step.
+
+## Step 2
+…
+`;
+}
+/**
+ * Validate a parsed custom skill beyond basic frontmatter parsing.
+ */
+export function validateSkill(skill, folderName) {
+    const issues = [];
+    if (skill.name !== folderName) {
+        issues.push({
+            level: 'error',
+            message: `Frontmatter name '${skill.name}' doesn't match folder '${folderName}'.`,
+        });
+    }
+    if (skill.description.length < 60) {
+        issues.push({
+            level: 'warning',
+            message: `Description is ${String(skill.description.length)} chars (recommend 60+).`,
+        });
+    }
+    if (!skill.prompt || skill.prompt.trim().length === 0) {
+        issues.push({
+            level: 'warning',
+            message: 'Body is empty.',
+        });
+    }
+    return issues;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",