@compilr-dev/sdk 0.29.1 → 0.29.2

package/dist/index.d.ts

@@ -67,7 +67,7 @@ export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from '
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig, FileArtifactServiceConfig, 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, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
+export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, InstalledFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
 export { RESERVED_MACRO_NAMES, isReservedMacroName, parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills, resolveLayeredSkills, resolveSkillsForAgent, resolveSkillsForTeamAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
 export type { SkillScope, SkillPromptResolution, AvailableSkillEntry, SkillSources, } from './skills/index.js';
 export { resolveSkillPrompt, getAllAvailableSkills } from './skills/index.js';
@@ -77,6 +77,8 @@ export { skillReachability, isUnreachable } from './skills/index.js';
 export { patchSkillFrontmatter } from './skills/index.js';
 export { isPlaceholderDescription } from './skills/index.js';
 export { readSkillFolder, unreadSkillFiles } from './skills/index.js';
+export { findInstallableSkills, normaliseSkillName, resolveInstallName, planInstall, describeInstallPlan, buildInstalledFromPatch, } from './skills/index.js';
+export type { InstallCandidate, InstallPlanItem } from './skills/index.js';
 export type { SkillFolderEntry } from './skills/index.js';
 export type { FrontmatterPatch } from './skills/index.js';
 export type { SkillReachability } from './skills/index.js';

package/dist/index.js

@@ -160,6 +160,7 @@ export { skillReachability, isUnreachable } from './skills/index.js';
 export { patchSkillFrontmatter } from './skills/index.js';
 export { isPlaceholderDescription } from './skills/index.js';
 export { readSkillFolder, unreadSkillFiles } from './skills/index.js';
+export { findInstallableSkills, normaliseSkillName, resolveInstallName, planInstall, describeInstallPlan, buildInstalledFromPatch, } from './skills/index.js';
 export { generateSkillCatalog, toCatalogEntry, createLoadSkillTool } from './skills/index.js';
 export { platformMacros, designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './skills/index.js';
 // =============================================================================

package/dist/skills/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Platform Skills — barrel export
  */
-export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker } from './types.js';
+export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, InstalledFromMarker, } from './types.js';
 export { RESERVED_MACRO_NAMES, isReservedMacroName } from './types.js';
 export { parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills } from './loader.js';
 export type { SkillEligibilityContext } from './resolver.js';
@@ -26,4 +26,6 @@ export type { SkillReachability } from './reachability.js';
 export { patchSkillFrontmatter } from './patch.js';
 export type { FrontmatterPatch } from './patch.js';
 export { readSkillFolder, unreadSkillFiles } from './folder.js';
+export { findInstallableSkills, normaliseSkillName, resolveInstallName, planInstall, describeInstallPlan, buildInstalledFromPatch, } from './install.js';
+export type { InstallCandidate, InstallPlanItem } from './install.js';
 export type { SkillFolderEntry } from './folder.js';

package/dist/skills/index.js

@@ -12,3 +12,4 @@ export { buildMacroInvocation } from './macro-invocation.js';
 export { skillReachability, isUnreachable } from './reachability.js';
 export { patchSkillFrontmatter } from './patch.js';
 export { readSkillFolder, unreadSkillFiles } from './folder.js';
+export { findInstallableSkills, normaliseSkillName, resolveInstallName, planInstall, describeInstallPlan, buildInstalledFromPatch, } from './install.js';

package/dist/skills/install.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Installing a skill someone else wrote.
+ *
+ * ⚠️ COPY, NEVER LINK. Skills load from exactly two directories, so *where the folder sits is its
+ * scope*. A reference would have no scope and would break the moment the source moved. A copy also
+ * means the edits are the user's own — which is the whole point of installing rather than reading.
+ *
+ * ⚠️ NOTHING AUTO-UPDATES, and that is deliberate. A copy has no link home. We record where it came
+ * from so a host can *tell* the user the source changed; we never reach back and change their file.
+ *
+ * Everything here is planned before a single byte is written. A source may hold dozens of skills
+ * (anthropics/skills does), two of them may want the same name, and a name may already be taken in
+ * the destination — the user sees every one of those resolutions *in advance*, as a name they can
+ * read, with the option to cancel. Silent resolution is the failure this module exists to avoid.
+ */
+import type { FrontmatterPatch } from './patch.js';
+import type { InstalledFromMarker } from './types.js';
+export interface InstallCandidate {
+    /** Folder name at the source. Not necessarily a legal skill name. */
+    folderName: string;
+    /** Absolute path of the folder holding SKILL.md. */
+    sourceDir: string;
+    /** From the file, so the selection list reads like the catalogue it will join. */
+    name: string;
+    description: string;
+    bodyLines: number;
+    /** Files beyond SKILL.md that will be copied along. */
+    extraFiles: number;
+    /**
+     * ⚠️ WE READ FRONTMATTER AND BODY ONLY. A skill that points at `references/` half-works and says
+     * nothing about it, so the count travels with the candidate and the host can warn before the copy
+     * rather than leaving it to a confused agent.
+     */
+    unreadFiles: number;
+}
+/**
+ * Every installable skill under `root`, depth-first to `maxDepth`.
+ *
+ * A folder holding SKILL.md IS a skill, so we never descend into one — its `references/` cannot
+ * contain skills, and a nested SKILL.md there would be part of the parent, not a sibling.
+ *
+ * Unreadable or unparseable folders are skipped rather than thrown: a source directory is someone
+ * else's, and one bad file must not make the other forty uninstallable.
+ */
+export declare function findInstallableSkills(root: string, maxDepth?: number): InstallCandidate[];
+/**
+ * A folder name turned into a legal skill name: lowercase, digits and hyphens, starting with a
+ * letter. Returns null when nothing legal survives, because inventing a name for someone else's
+ * skill is worse than refusing it.
+ */
+export declare function normaliseSkillName(folderName: string): string | null;
+/**
+ * The name this skill will actually land as, given what is already there.
+ *
+ * `pdf` when free, otherwise `pdf-2`, `pdf-3`… The suffix is plain and always appended, so the
+ * result is predictable from the inputs — and it is shown to the user before anything is written,
+ * which is what makes an ugly-but-honest name better than a clever one.
+ */
+export declare function resolveInstallName(desired: string, taken: Iterable<string>): string;
+export interface InstallPlanItem {
+    candidate: InstallCandidate;
+    /** The folder name it will be written as. */
+    finalName: string;
+    /** Set when the source folder name was not a legal skill name. */
+    renamedFrom: string | null;
+    /** Set when `finalName` differs from the wanted name because something already holds it. */
+    collidedWith: string | null;
+    /** Why it cannot be installed at all. When set, nothing about this item is written. */
+    blocked: string | null;
+    /** The built-in name it would have shadowed, which is why it was renamed. */
+    shadowedBuiltin: string | null;
+}
+/**
+ * What installing this selection would do, resolved in full before anything is written.
+ *
+ * ⚠️ COLLISIONS ACCUMULATE WITHIN THE BATCH. Two sources both called `pdf` collide with each other,
+ * not just with the destination — so each resolved name joins the taken set as it is decided.
+ * Getting this wrong means the second copy silently overwrites the first.
+ */
+export declare function planInstall(candidates: InstallCandidate[], existingNames: Iterable<string>): InstallPlanItem[];
+/**
+ * One sentence per resolution, for showing the user before they commit.
+ *
+ * Returns [] when nothing needs saying — which is the common case, and must not render as an empty
+ * warning box.
+ */
+export declare function describeInstallPlan(plan: InstallPlanItem[]): string[];
+/**
+ * The frontmatter edit that records where a skill came from.
+ *
+ * ⚠️ A PATCH, NOT A REWRITE (D-2). This runs on a file someone else wrote — their comments, key
+ * order and fields we have never modelled all have to survive being installed, or we have silently
+ * edited a stranger's skill on its way in.
+ */
+export declare function buildInstalledFromPatch(marker: InstalledFromMarker): FrontmatterPatch;

package/dist/skills/install.js

@@ -0,0 +1,214 @@
+/**
+ * Installing a skill someone else wrote.
+ *
+ * ⚠️ COPY, NEVER LINK. Skills load from exactly two directories, so *where the folder sits is its
+ * scope*. A reference would have no scope and would break the moment the source moved. A copy also
+ * means the edits are the user's own — which is the whole point of installing rather than reading.
+ *
+ * ⚠️ NOTHING AUTO-UPDATES, and that is deliberate. A copy has no link home. We record where it came
+ * from so a host can *tell* the user the source changed; we never reach back and change their file.
+ *
+ * Everything here is planned before a single byte is written. A source may hold dozens of skills
+ * (anthropics/skills does), two of them may want the same name, and a name may already be taken in
+ * the destination — the user sees every one of those resolutions *in advance*, as a name they can
+ * read, with the option to cancel. Silent resolution is the failure this module exists to avoid.
+ */
+import { readdirSync, statSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { isValidSkillName } from './paths.js';
+import { isReservedMacroName } from './types.js';
+import { parseSkillMarkdown } from './loader.js';
+import { readSkillFolder } from './folder.js';
+const SKIP_DIRS = new Set(['node_modules', '.git', '.github', 'dist', 'build', '__pycache__']);
+/**
+ * Every installable skill under `root`, depth-first to `maxDepth`.
+ *
+ * A folder holding SKILL.md IS a skill, so we never descend into one — its `references/` cannot
+ * contain skills, and a nested SKILL.md there would be part of the parent, not a sibling.
+ *
+ * Unreadable or unparseable folders are skipped rather than thrown: a source directory is someone
+ * else's, and one bad file must not make the other forty uninstallable.
+ */
+export function findInstallableSkills(root, maxDepth = 3) {
+    const out = [];
+    const visit = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        if (entries.includes('SKILL.md')) {
+            const candidate = describeCandidate(dir);
+            if (candidate)
+                out.push(candidate);
+            return; // a skill is a leaf
+        }
+        if (depth >= maxDepth)
+            return;
+        for (const name of entries.sort()) {
+            if (SKIP_DIRS.has(name) || name.startsWith('.'))
+                continue;
+            try {
+                if (statSync(join(dir, name)).isDirectory())
+                    visit(join(dir, name), depth + 1);
+            }
+            catch {
+                /* unreadable entry — skip it, not the whole source */
+            }
+        }
+    };
+    visit(root, 0);
+    return out;
+}
+function describeCandidate(dir) {
+    let content;
+    try {
+        content = readFileSync(join(dir, 'SKILL.md'), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const parsed = parseSkillMarkdown(content, dir);
+    if (!parsed)
+        return null;
+    const body = parsed.prompt.trim();
+    return {
+        folderName: basename(dir),
+        sourceDir: dir,
+        name: parsed.name,
+        description: parsed.description,
+        bodyLines: body === '' ? 0 : body.split('\n').length,
+        extraFiles: readSkillFolder(dir).length,
+        unreadFiles: readSkillFolder(dir).filter((f) => f.kind === 'reference' || f.kind === 'script')
+            .length,
+    };
+}
+/**
+ * A folder name turned into a legal skill name: lowercase, digits and hyphens, starting with a
+ * letter. Returns null when nothing legal survives, because inventing a name for someone else's
+ * skill is worse than refusing it.
+ */
+export function normaliseSkillName(folderName) {
+    const slug = folderName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64)
+        .replace(/-+$/, '');
+    return isValidSkillName(slug) ? slug : null;
+}
+/**
+ * The name this skill will actually land as, given what is already there.
+ *
+ * `pdf` when free, otherwise `pdf-2`, `pdf-3`… The suffix is plain and always appended, so the
+ * result is predictable from the inputs — and it is shown to the user before anything is written,
+ * which is what makes an ugly-but-honest name better than a clever one.
+ */
+export function resolveInstallName(desired, taken) {
+    const used = new Set(taken);
+    if (!used.has(desired))
+        return desired;
+    for (let n = 2; n < 1000; n++) {
+        const next = `${desired}-${String(n)}`;
+        if (!used.has(next))
+            return next;
+    }
+    return `${desired}-${String(Date.now())}`;
+}
+/**
+ * What installing this selection would do, resolved in full before anything is written.
+ *
+ * ⚠️ COLLISIONS ACCUMULATE WITHIN THE BATCH. Two sources both called `pdf` collide with each other,
+ * not just with the destination — so each resolved name joins the taken set as it is decided.
+ * Getting this wrong means the second copy silently overwrites the first.
+ */
+export function planInstall(candidates, existingNames) {
+    const taken = new Set(existingNames);
+    return candidates.map((candidate) => {
+        const wanted = normaliseSkillName(candidate.folderName);
+        if (wanted === null) {
+            return {
+                candidate,
+                finalName: candidate.folderName,
+                renamedFrom: null,
+                collidedWith: null,
+                blocked: `"${candidate.folderName}" cannot become a skill name — rename the folder and try again.`,
+                shadowedBuiltin: null,
+            };
+        }
+        /*
+          ⚠️ A RESERVED NAME IS NOT A FREE NAME. Project and user scope outrank `sdk` in
+          resolveSkillPrompt, so installing someone's `design` would silently become /design in both
+          hosts and the collision detector would stay quiet — the same defect `skills:create` already
+          refuses. Renaming rather than blocking: the user still gets the skill, it just cannot
+          impersonate a built-in.
+        */
+        if (isReservedMacroName(wanted)) {
+            const renamed = resolveInstallName(`${wanted}-installed`, taken);
+            taken.add(renamed);
+            return {
+                candidate,
+                finalName: renamed,
+                renamedFrom: candidate.folderName === renamed ? null : candidate.folderName,
+                collidedWith: wanted,
+                blocked: null,
+                shadowedBuiltin: wanted,
+            };
+        }
+        const finalName = resolveInstallName(wanted, taken);
+        taken.add(finalName);
+        return {
+            candidate,
+            finalName,
+            renamedFrom: wanted === candidate.folderName ? null : candidate.folderName,
+            collidedWith: finalName === wanted ? null : wanted,
+            blocked: null,
+            shadowedBuiltin: null,
+        };
+    });
+}
+/**
+ * One sentence per resolution, for showing the user before they commit.
+ *
+ * Returns [] when nothing needs saying — which is the common case, and must not render as an empty
+ * warning box.
+ */
+export function describeInstallPlan(plan) {
+    const out = [];
+    for (const item of plan) {
+        if (item.blocked) {
+            out.push(item.blocked);
+        }
+        else if (item.shadowedBuiltin) {
+            out.push(`${item.shadowedBuiltin} is a built-in — installing it under that name would silently replace it everywhere, so this will land as ${item.finalName}.`);
+        }
+        else if (item.collidedWith && item.renamedFrom) {
+            out.push(`"${item.renamedFrom}" is not a legal skill name and ${item.collidedWith} is already here — it will land as ${item.finalName}.`);
+        }
+        else if (item.collidedWith) {
+            out.push(`A skill called ${item.collidedWith} already exists here — this will land as ${item.finalName}.`);
+        }
+        else if (item.renamedFrom) {
+            out.push(`"${item.renamedFrom}" is not a legal skill name — it will land as ${item.finalName}.`);
+        }
+    }
+    return out;
+}
+/**
+ * The frontmatter edit that records where a skill came from.
+ *
+ * ⚠️ A PATCH, NOT A REWRITE (D-2). This runs on a file someone else wrote — their comments, key
+ * order and fields we have never modelled all have to survive being installed, or we have silently
+ * edited a stranger's skill on its way in.
+ */
+export function buildInstalledFromPatch(marker) {
+    return {
+        installedFrom: {
+            source: marker.source,
+            skill: marker.skill,
+            installedAt: marker.installedAt,
+        },
+    };
+}

package/dist/skills/loader.js

@@ -93,6 +93,9 @@ export function parseSkillMarkdown(content, sourcePath, source) {
     if (meta['forkedFrom'] && typeof meta['forkedFrom'] === 'object') {
         skill.forkedFrom = meta['forkedFrom'];
     }
+    if (meta['installedFrom'] && typeof meta['installedFrom'] === 'object') {
+        skill.installedFrom = meta['installedFrom'];
+    }
     return skill;
 }
 /**

package/dist/skills/patch.d.ts

@@ -14,8 +14,19 @@
  *
  * Decision D-2: project-docs/.../compilr-dev-skills/implementation-plan.md
  */
-/** `undefined` leaves a key alone; `null` removes it; anything else sets it. */
-export type FrontmatterPatch = Record<string, string | number | boolean | null | undefined>;
+/**
+ * `undefined` leaves a key alone; `null` removes it; anything else sets it.
+ *
+ * A plain object becomes a nested block — the shape `forkedFrom` already has on disk:
+ *
+ *     installedFrom:
+ *       source: "/home/me/skills"
+ *       skill: "pdf"
+ *
+ * ⚠️ NOT A ONE-LINE FLOW MAPPING. `{ a: 1 }` passed as a string would sail past the 80-character
+ * threshold below, come back out as a block scalar, and parse as a STRING that reads like a map.
+ */
+export type FrontmatterPatch = Record<string, string | number | boolean | Record<string, string> | null | undefined>;
 /**
  * Apply `patch` to `content`'s frontmatter, leaving everything else byte-identical.
  *

package/dist/skills/patch.js

@@ -51,7 +51,17 @@ function keyBlockEnd(lines, start) {
         end--;
     return end;
 }
+/** YAML double-quoted scalar. Quoted always, so a value starting with `/` or `{` stays a string. */
+function quote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
 function render(key, value) {
+    if (typeof value === 'object') {
+        const body = Object.entries(value)
+            .map(([k, v]) => `  ${k}: ${quote(v)}`)
+            .join('\n');
+        return body === '' ? `${key}: {}` : `${key}:\n${body}`;
+    }
     if (typeof value === 'string' && (value.includes('\n') || value.length > 80)) {
         const body = value
             .split('\n')

package/dist/skills/types.d.ts

@@ -45,6 +45,17 @@ export interface ForkedFromMarker {
     version: string;
     forkedAt: string;
 }
+/**
+ * Where an installed skill came from. Recorded on the way in, never used to fetch: nothing
+ * auto-updates, so this exists so a host can TELL the user the source moved on.
+ */
+export interface InstalledFromMarker {
+    /** Verbatim: the folder path or repo URL the user gave. */
+    source: string;
+    /** The folder name at the source, which differs from the installed name after a collision. */
+    skill: string;
+    installedAt: string;
+}
 /**
  * Custom skill — matches Anthropic spec + compilr extensions.
  *
@@ -96,6 +107,8 @@ export interface CustomSkill {
     compilr?: CompilrSkillExtension;
     /** Set when this skill was created via /skill fork. */
     forkedFrom?: ForkedFromMarker;
+    /** Present only on skills installed from someone else's folder or repo. */
+    installedFrom?: InstalledFromMarker;
     /** Absolute path to the skill directory (containing SKILL.md). */
     sourcePath?: string;
     /** Where this skill came from. */

package/package.json

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