vskill 1.0.14 → 1.0.16

package/dist/clone/reference-scanner.js

@@ -0,0 +1,144 @@
+// ---------------------------------------------------------------------------
+// vskill clone — reference-scanner (READ-ONLY)
+// ---------------------------------------------------------------------------
+// Detects cross-skill reference patterns and self-name occurrences in
+// SKILL.md prose. **Reports only — never rewrites anything.** The orchestrator
+// appends the report to the success summary so the user can decide what to do.
+//
+// Patterns:
+//   - backtick:       `sw:foo`             (single-backtick inline code)
+//   - skill-call:     Skill({ skill: "sw:foo" })  /  Skill({ skill: 'sw:foo' })
+//   - slash-command:  /sw:foo
+//   - self-name:      literal occurrence of the OLD skill name in prose
+//
+// False-positive guard: matches inside fenced code blocks (```...```) are
+// excluded for the slash-command and self-name patterns. Backtick and
+// Skill({...}) patterns are themselves code-shaped, so they are reported
+// unconditionally — that's the user's signal that an actual cross-skill
+// dependency exists in the source.
+//
+// See spec.md AC-US1-04, plan.md §6.
+// ---------------------------------------------------------------------------
+const BACKTICK_RE = /`([a-z][a-z0-9-]*:[a-z][a-z0-9-]*)`/g;
+const SKILL_CALL_RE = /Skill\s*\(\s*\{\s*skill\s*:\s*["']([^"']+)["']/g;
+const SLASH_COMMAND_RE = /(?:^|\s)(\/[a-z][a-z0-9-]*:[a-z][a-z0-9-]*)\b/g;
+/**
+ * Build a regex that matches the OLD skill name as a whole "word", where word
+ * boundaries here mean the surrounding chars are not [A-Za-z0-9-/] (so
+ * "ado-mapper" matches but "ado-mapperx" or "my-ado-mapper-thing" do not).
+ *
+ * The `oldSkillName` is escaped before being embedded in the pattern so any
+ * regex metacharacters in the skill name are treated literally.
+ */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Detect lines covered by fenced code blocks (triple-backtick). Returns a Set
+ * of 1-indexed line numbers that are INSIDE a fence. Used to suppress
+ * slash-command and self-name false positives that live in code samples.
+ *
+ * The opening/closing fence lines themselves are also considered "inside"
+ * for the purpose of suppression — they don't contain meaningful prose
+ * references, so this is a deliberate slight overreach.
+ */
+function computeFencedLines(lines) {
+    const fenced = new Set();
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trimStart();
+        if (trimmed.startsWith("```")) {
+            // The fence-opening line and fence-closing line are both fenced.
+            fenced.add(i + 1);
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            fenced.add(i + 1);
+    }
+    return fenced;
+}
+/**
+ * Scan SKILL.md content for cross-skill references and self-name occurrences.
+ * Returns matches in document order with line numbers (1-indexed).
+ */
+export function scanReferences(content, opts) {
+    const file = opts.file ?? "SKILL.md";
+    const normalized = content.replace(/^/, "").replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    const fenced = computeFencedLines(lines);
+    const out = [];
+    // Pattern 1: backtick `sw:foo` — reported unconditionally (already code-shaped).
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        BACKTICK_RE.lastIndex = 0;
+        let m;
+        while ((m = BACKTICK_RE.exec(line)) !== null) {
+            out.push({ file, line: i + 1, match: m[1], kind: "backtick" });
+        }
+    }
+    // Pattern 2: Skill({ skill: "sw:foo" }) — reported unconditionally.
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        SKILL_CALL_RE.lastIndex = 0;
+        let m;
+        while ((m = SKILL_CALL_RE.exec(line)) !== null) {
+            out.push({ file, line: i + 1, match: m[1], kind: "skill-call" });
+        }
+    }
+    // Pattern 3: /sw:foo — slash-command. Suppressed inside fenced code blocks.
+    for (let i = 0; i < lines.length; i++) {
+        if (fenced.has(i + 1))
+            continue;
+        const line = lines[i];
+        SLASH_COMMAND_RE.lastIndex = 0;
+        let m;
+        while ((m = SLASH_COMMAND_RE.exec(line)) !== null) {
+            // Strip the leading "/" so the recorded match is the bare slash-command name.
+            const matched = m[1];
+            out.push({ file, line: i + 1, match: matched, kind: "slash-command" });
+        }
+    }
+    return out;
+}
+/**
+ * Scan for literal occurrences of the OLD skill name in prose.
+ * Suppressed inside fenced code blocks. Returned as a separate array because
+ * it's informational at a different level (manual rename candidates, not
+ * cross-skill dependencies).
+ */
+export function scanSelfNameOccurrences(content, opts) {
+    const file = opts.file ?? "SKILL.md";
+    const normalized = content.replace(/^/, "").replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    const fenced = computeFencedLines(lines);
+    // The full name may contain "/" (e.g. "sw/ado-mapper") — we scan for both
+    // the bare skill segment and the full name. Bare segment first ensures we
+    // catch occurrences like "the ado-mapper does X" in prose.
+    const slashIdx = opts.oldSkillName.indexOf("/");
+    const bareSkill = slashIdx >= 0 ? opts.oldSkillName.slice(slashIdx + 1) : opts.oldSkillName;
+    const patterns = new Set();
+    patterns.add(opts.oldSkillName);
+    if (bareSkill !== opts.oldSkillName)
+        patterns.add(bareSkill);
+    const out = [];
+    for (const pattern of patterns) {
+        const escaped = escapeRegex(pattern);
+        // Word-boundary that treats letters, digits, hyphen, slash as part of the "word".
+        // (?<![A-Za-z0-9-/])  — preceded by neither a name char nor a slash
+        // (?![A-Za-z0-9-/])   — followed by neither a name char nor a slash
+        const re = new RegExp(`(?<![A-Za-z0-9\\-/])${escaped}(?![A-Za-z0-9\\-/])`, "g");
+        for (let i = 0; i < lines.length; i++) {
+            if (fenced.has(i + 1))
+                continue;
+            const line = lines[i];
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(line)) !== null) {
+                out.push({ file, line: i + 1, match: m[0], kind: "self-name" });
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=reference-scanner.js.map

package/dist/clone/reference-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-scanner.js","sourceRoot":"","sources":["../../src/clone/reference-scanner.ts"],"names":[],"mappings":"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"}

package/dist/clone/skill-locator.d.ts

@@ -0,0 +1,26 @@
+import type { SkillSource } from "./types.js";
+export interface LocateOptions {
+    /** Working directory to use as the project root (defaults to process.cwd()). */
+    cwd?: string;
+    /** Home directory (defaults to os.homedir() — explicit for testability). */
+    home: string;
+}
+/**
+ * Split a source identifier like "sw/ado-mapper" into namespace + skill, or
+ * return only the skill when no namespace is present.
+ */
+export declare function parseSourceIdent(source: string): {
+    namespace?: string;
+    skill: string;
+};
+/**
+ * Discover a skill across project / personal / cache. Returns every match in
+ * search order — the orchestrator handles disambiguation when there is more
+ * than one and `--source` was not explicitly provided.
+ */
+export declare function locateSkill(source: string, opts: LocateOptions): Promise<SkillSource[]>;
+/**
+ * Enumerate every skill inside a cached plugin. Used by the whole-plugin
+ * clone path (T-010). Returns a list of SkillSource entries (one per skill).
+ */
+export declare function enumeratePluginSkills(pluginName: string, opts: LocateOptions): Promise<SkillSource[]>;

package/dist/clone/skill-locator.js

@@ -0,0 +1,248 @@
+// ---------------------------------------------------------------------------
+// vskill clone — skill-locator
+// ---------------------------------------------------------------------------
+// Discover a source skill across the three supported locations, in deterministic
+// order. The caller (orchestrator in src/commands/clone.ts) decides what to do
+// with multiple matches (interactive disambiguation or honor --source override).
+//
+// Search order:
+//   1. project   → <cwd>/.claude/skills/<skill>/SKILL.md
+//   2. personal  → <home>/.claude/skills/<skill>/SKILL.md
+//   3. cache     → <home>/.claude/plugins/cache/<org>/<plugin>/<version>/skills/<skill>/SKILL.md
+//
+// Source identifiers may be passed as:
+//   - "ado-mapper"     (bare skill name)
+//   - "sw/ado-mapper"  (namespace/skill — namespace is treated informationally)
+//
+// See spec.md AC-US1-01 and plan.md §4.
+// ---------------------------------------------------------------------------
+import { promises as fs } from "node:fs";
+import { join, basename } from "node:path";
+import { readProvenance } from "../studio/lib/provenance.js";
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+const NAME_LINE_RE = /^name:\s*(.+?)\s*$/m;
+const VERSION_LINE_RE = /^version:\s*(.+?)\s*$/m;
+function unquote(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+async function parseSkillMd(skillMdPath) {
+    try {
+        const raw = await fs.readFile(skillMdPath, "utf-8");
+        const normalized = raw.replace(/^/, "").replace(/\r\n/g, "\n");
+        const fmMatch = normalized.match(FRONTMATTER_RE);
+        if (!fmMatch)
+            return {};
+        const block = fmMatch[1];
+        const nameMatch = block.match(NAME_LINE_RE);
+        const versionMatch = block.match(VERSION_LINE_RE);
+        return {
+            name: nameMatch ? unquote(nameMatch[1]) : undefined,
+            version: versionMatch ? unquote(versionMatch[1]) : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Split a source identifier like "sw/ado-mapper" into namespace + skill, or
+ * return only the skill when no namespace is present.
+ */
+export function parseSourceIdent(source) {
+    const idx = source.indexOf("/");
+    if (idx === -1)
+        return { skill: source };
+    return { namespace: source.slice(0, idx), skill: source.slice(idx + 1) };
+}
+async function exists(path) {
+    try {
+        await fs.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function dirExists(path) {
+    try {
+        const st = await fs.stat(path);
+        return st.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function buildSource(location, skillDir, fallbackSkillName, pluginCtx) {
+    const skillMd = join(skillDir, "SKILL.md");
+    if (!(await exists(skillMd)))
+        return null;
+    const fm = await parseSkillMd(skillMd);
+    const fullName = fm.name ?? fallbackSkillName;
+    const slashIdx = fullName.indexOf("/");
+    const namespace = slashIdx >= 0 ? fullName.slice(0, slashIdx) : undefined;
+    let existingProvenance = null;
+    try {
+        existingProvenance = await readProvenance(skillDir);
+    }
+    catch {
+        existingProvenance = null;
+    }
+    return {
+        location,
+        skillDir,
+        skillName: fullName,
+        namespace,
+        version: fm.version ?? "0.0.0",
+        plugin: pluginCtx,
+        existingProvenance,
+    };
+}
+async function locateInProject(cwd, skill) {
+    const dir = join(cwd, ".claude", "skills", skill);
+    if (!(await dirExists(dir)))
+        return null;
+    return buildSource("project", dir, skill);
+}
+async function locateInPersonal(home, skill) {
+    const dir = join(home, ".claude", "skills", skill);
+    if (!(await dirExists(dir)))
+        return null;
+    return buildSource("personal", dir, skill);
+}
+async function locateInCache(home, skill, preferredNamespace) {
+    const cacheRoot = join(home, ".claude", "plugins", "cache");
+    if (!(await dirExists(cacheRoot)))
+        return [];
+    const matches = [];
+    let orgs;
+    try {
+        orgs = await fs.readdir(cacheRoot);
+    }
+    catch {
+        return [];
+    }
+    for (const org of orgs) {
+        const orgDir = join(cacheRoot, org);
+        if (!(await dirExists(orgDir)))
+            continue;
+        let plugins;
+        try {
+            plugins = await fs.readdir(orgDir);
+        }
+        catch {
+            continue;
+        }
+        for (const pluginName of plugins) {
+            const pluginRoot = join(orgDir, pluginName);
+            if (!(await dirExists(pluginRoot)))
+                continue;
+            let versions;
+            try {
+                versions = await fs.readdir(pluginRoot);
+            }
+            catch {
+                continue;
+            }
+            for (const version of versions) {
+                const skillDir = join(pluginRoot, version, "skills", skill);
+                if (!(await dirExists(skillDir)))
+                    continue;
+                const built = await buildSource("cache", skillDir, skill, {
+                    pluginNamespace: org,
+                    pluginName,
+                    pluginVersion: version,
+                    pluginRoot: join(pluginRoot, version),
+                });
+                if (!built)
+                    continue;
+                if (preferredNamespace && built.namespace && built.namespace !== preferredNamespace) {
+                    continue;
+                }
+                matches.push(built);
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * Discover a skill across project / personal / cache. Returns every match in
+ * search order — the orchestrator handles disambiguation when there is more
+ * than one and `--source` was not explicitly provided.
+ */
+export async function locateSkill(source, opts) {
+    const { skill, namespace } = parseSourceIdent(source);
+    const cwd = opts.cwd ?? process.cwd();
+    const matches = [];
+    const project = await locateInProject(cwd, skill);
+    if (project && (!namespace || project.namespace === namespace || !project.namespace)) {
+        matches.push(project);
+    }
+    const personal = await locateInPersonal(opts.home, skill);
+    if (personal && (!namespace || personal.namespace === namespace || !personal.namespace)) {
+        matches.push(personal);
+    }
+    const cache = await locateInCache(opts.home, skill, namespace);
+    matches.push(...cache);
+    return matches;
+}
+/**
+ * Enumerate every skill inside a cached plugin. Used by the whole-plugin
+ * clone path (T-010). Returns a list of SkillSource entries (one per skill).
+ */
+export async function enumeratePluginSkills(pluginName, opts) {
+    const cacheRoot = join(opts.home, ".claude", "plugins", "cache");
+    if (!(await dirExists(cacheRoot)))
+        return [];
+    const results = [];
+    let orgs;
+    try {
+        orgs = await fs.readdir(cacheRoot);
+    }
+    catch {
+        return [];
+    }
+    for (const org of orgs) {
+        const pluginRoot = join(cacheRoot, org, pluginName);
+        if (!(await dirExists(pluginRoot)))
+            continue;
+        let versions;
+        try {
+            versions = await fs.readdir(pluginRoot);
+        }
+        catch {
+            continue;
+        }
+        for (const version of versions) {
+            const skillsDir = join(pluginRoot, version, "skills");
+            if (!(await dirExists(skillsDir)))
+                continue;
+            let skillEntries;
+            try {
+                skillEntries = await fs.readdir(skillsDir);
+            }
+            catch {
+                continue;
+            }
+            for (const skillEntry of skillEntries) {
+                const skillDir = join(skillsDir, skillEntry);
+                if (!(await dirExists(skillDir)))
+                    continue;
+                const built = await buildSource("cache", skillDir, basename(skillDir), {
+                    pluginNamespace: org,
+                    pluginName,
+                    pluginVersion: version,
+                    pluginRoot: join(pluginRoot, version),
+                });
+                if (built)
+                    results.push(built);
+            }
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=skill-locator.js.map

package/dist/clone/skill-locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-locator.js","sourceRoot":"","sources":["../../src/clone/skill-locator.ts"],"names":[],"mappings":"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"}

package/dist/clone/target-router.d.ts

@@ -0,0 +1,73 @@
+import { basename } from "node:path";
+export interface CopyResult {
+    /** Absolute path of the `.tmp` staging directory. Caller renames into place. */
+    stagingDir: string;
+    /** Number of files written under `stagingDir`. */
+    filesCopied: number;
+    /** Final destination path (where `stagingDir` should be renamed to). */
+    finalDir: string;
+}
+export interface PluginCopyResult extends CopyResult {
+    /** Absolute path of the `.tmp` staged plugin manifest (sibling of the live manifest). */
+    manifestTmpPath: string;
+    /** Absolute path of the live plugin manifest (final rename target). */
+    manifestFinalPath: string;
+}
+/** Compute the `.tmp` sibling of a final destination path. */
+export declare function tmpSibling(finalPath: string): string;
+/**
+ * Best-effort cleanup of a `.tmp` path. Mirrors the rollback shape used by
+ * src/commands/add.ts:rollbackInstall — swallows per-call errors so a partial
+ * filesystem state doesn't suppress the underlying diagnostic the orchestrator
+ * is about to surface to the user.
+ */
+export declare function bestEffortRm(path: string): void;
+/**
+ * Copy a source skill into a fresh standalone target dir, staged at
+ * `<finalDir>.tmp`. The orchestrator is responsible for the atomic
+ * rename and any pre-checks for collisions / `--force`.
+ */
+export declare function writeStandalone(args: {
+    sourceSkillDir: string;
+    finalDir: string;
+}): Promise<CopyResult>;
+/**
+ * Copy a source skill into an existing user-owned plugin's skills/ directory
+ * AND stage an updated `plugin.json` at `<plugin.json>.tmp` so the
+ * orchestrator can rename both in sequence (two-phase commit).
+ *
+ * Pre-flight: detects malformed plugin.json BEFORE any copy is staged
+ * (AC-US2-03). Caller aborts on the thrown error; no skill files are written.
+ */
+export declare function writeToPlugin(args: {
+    sourceSkillDir: string;
+    pluginRoot: string;
+    newSkillName: string;
+}): Promise<PluginCopyResult>;
+/**
+ * Scaffold a fresh new plugin at `<pluginRoot>` containing
+ * `.claude-plugin/plugin.json` (with the requested name) plus
+ * `skills/<skill>/` subtree containing the cloned skill.
+ *
+ * The whole plugin tree is staged at `<pluginRoot>.tmp` and atomically
+ * renamed by the caller — there is no two-phase commit because the manifest
+ * and the skill files live under a common root (one `rename` is enough).
+ */
+export declare function writeNewPlugin(args: {
+    sourceSkillDir: string;
+    pluginRoot: string;
+    pluginName: string;
+    newSkillName: string;
+    /** Optional plugin description; defaults to a generic forked-skills line. */
+    description?: string;
+    /** Optional plugin author; recorded in plugin.json. */
+    author?: string;
+}): Promise<CopyResult>;
+/**
+ * The `bareSkillName` helper extracts the unqualified skill name from a
+ * fully-qualified name like `anton/ado-mapper` → `ado-mapper`. Used by the
+ * orchestrator and by callers that need the directory-safe segment.
+ */
+export declare function bareSkillName(fullyQualified: string): string;
+/** Re-export for callers that want to validate basenames. */
+export { basename };