@serviceme/devtools-core 0.1.8 → 0.2.0

package/dist/skill-linker.d.mts

@@ -0,0 +1,188 @@
+/**
+ * Skill & Agent v2 — Client SkillLinker (M3, path-parity revision)
+ *
+ * SkillLinker exposes a skill/agent from the user's global repos
+ * (`~/.serviceme/repos/<repoId>/{skills,agents}/<name>/`) into either:
+ *
+ *   - a workspace, at `<workspace>/.github/{skills,agents}/<name>` —
+ *     the same path Copilot/Claude actually scan for `SKILL.md` /
+ *     `AGENT.md`, so linking here has real effect (see the v1 parity
+ *     note below); or
+ *   - the user's global scope, at `~/.agents/{skills,agents}/<name>`,
+ *     visible to every workspace.
+ *
+ * **v1 parity note**: an earlier revision linked into a private
+ * `<workspace>/.serviceme/skills/<repoId>/<name>` directory. That path
+ * is never scanned by the actual tooling, so installs were silently
+ * inert. The path was moved to match `.github/skills` (the same
+ * location the legacy v1 marketplace pipeline used). Because the link
+ * path is now flat (no `<repoId>` segment), only one repo's version of
+ * a given `<name>` can be linked into a given scope at a time.
+ *
+ * Platform behavior (per spec §11.8 — owner explicitly chose throw
+ * over silent copy fallback):
+ *
+ * | platform | default mode | on failure                  |
+ * |----------|--------------|-----------------------------|
+ * | macOS    | symlink      | throw + platform hint       |
+ * | Linux    | symlink      | throw + platform hint       |
+ * | Windows  | junction     | throw + platform hint       |
+ *
+ * Why junction first on Windows: NTFS junction doesn't require
+ * SeCreateSymbolicLinkPrivilege; it works for any user. The limit is
+ * the link target must be on a local NTFS volume. OneDrive / network
+ * shares sometimes fail; we surface that as a typed error so callers
+ * can decide whether to retry.
+ *
+ * @see docs/architecture/skill-agent-v2-repo.md §5.6 SkillLinker
+ * @see docs/architecture/skill-agent-v2-repo.md §11.8 (throw, not copy)
+ */
+type LinkMode = "symlink" | "junction" | "copy";
+/** Kind of artifact being linked. Mirrors `BridgeSkillKind`. */
+type EntryKind = "skill" | "agent";
+/**
+ * Which scope the link lives in:
+ *   - `"workspace"` (default) → `<workspaceDir>/.github/<kind>/<name>`
+ *   - `"user"` → `~/.agents/<kind>/<name>` (visible to every workspace)
+ */
+type LinkScope = "workspace" | "user";
+interface InstallSkillOptions {
+    repoId: string;
+    skillName: string;
+    workspaceDir: string;
+    /** Choose link mode explicitly. Defaults to platform-optimal. */
+    mode?: "auto" | LinkMode;
+    /** "skill" (default) or "agent". */
+    kind?: EntryKind;
+    /** "workspace" (default) or "user". */
+    scope?: LinkScope;
+    /**
+     * Pre-resolved absolute source path (from `SkillStore`), overriding
+     * the `<repoRoot>/{skills,agents}/<name>` formula in
+     * {@link resolveSkillTarget}. Required for repos with non-standard
+     * layouts — flat root (no `skills/` prefix), nested scope dirs
+     * (`skills/official/<name>`), or flat single-file agent manifests
+     * (`agents/<name>.agent.md`) — which the formula can't predict.
+     * When omitted, falls back to the formula (kept for callers that
+     * install a hand-authored skill without going through `SkillStore`).
+     */
+    sourcePath?: string;
+    /**
+     * True when `sourcePath` points at a single manifest FILE (e.g. a
+     * flat `<name>.agent.md`) rather than a directory. Determines the
+     * symlink type (file vs dir/junction) and the link's basename (the
+     * link mirrors the source file's name + extension, since Copilot/
+     * VS Code scan `.github/agents/<name>.agent.md` as a FILE).
+     */
+    sourceIsFile?: boolean;
+}
+interface InstallSkillResult {
+    mode: LinkMode;
+    linkPath: string;
+    targetPath: string;
+}
+/** Describes one symlink/junction currently present in a workspace/user scope. */
+interface LinkedSkill {
+    /**
+     * Repo id the link resolves to, parsed back out of the symlink
+     * target. Empty string when the target isn't under a recognizable
+     * `~/.serviceme/repos/<repoId>/...` path.
+     */
+    repoId: string;
+    skillName: string;
+    linkPath: string;
+    targetPath: string;
+    mode: LinkMode;
+    /** Which scope this link was found in — "workspace" or "user" (global). */
+    scope: LinkScope;
+}
+/**
+ * Sentinel error for link failures. Carries the chosen mode + platform
+ * hint so the UI can render an actionable message.
+ */
+declare class LinkError extends Error {
+    readonly mode: LinkMode;
+    readonly target: string;
+    readonly linkPath: string;
+    readonly platform: NodeJS.Platform;
+    readonly cause: unknown;
+    constructor(opts: {
+        mode: LinkMode;
+        target: string;
+        linkPath: string;
+        platform: NodeJS.Platform;
+        cause: unknown;
+    });
+    /** A user-facing hint for the platform that failed. */
+    hint(): string;
+}
+/** Choose the platform-optimal link mode. */
+declare function pickMode(platform?: NodeJS.Platform): LinkMode;
+/** A short hint string for the platform where the link failed. */
+declare function getPlatformHint(platform: NodeJS.Platform): string;
+/**
+ * Resolve the source path inside `~/.serviceme/repos/<repoId>/{skills,agents}/<name>`.
+ * Exported for callers that need to inspect the target without installing.
+ */
+declare function resolveSkillTarget(repoId: string, skillName: string, kind?: EntryKind): string;
+/**
+ * Resolve the workspace link path — `<workspaceDir>/.github/{skills,agents}/<name>` —
+ * the same directory Copilot/Claude actually scan.
+ */
+declare function resolveSkillLinkPath(workspaceDir: string, skillName: string, kind?: EntryKind): string;
+/**
+ * Resolve the user-scope link path — `~/.agents/{skills,agents}/<name>` —
+ * visible to every workspace.
+ */
+declare function resolveUserSkillLinkPath(skillName: string, kind?: EntryKind): string;
+/**
+ * Install a skill into a workspace by creating a link at the standard
+ * path. Throws `LinkError` on failure (no silent copy fallback per
+ * §11.8).
+ *
+ * Idempotent: if the correct link already exists, returns the existing
+ * record without touching the filesystem. If a *wrong* link exists at
+ * the target path, it is replaced.
+ */
+declare function installSkillToWorkspace(opts: InstallSkillOptions): Promise<InstallSkillResult>;
+/**
+ * Convert an existing, real (non-symlink) skill/agent directory at the
+ * standard scan path into a symlink pointing at the matching global
+ * repo entry. Refuses to run when there's nothing real to convert —
+ * callers should only surface this action when a marketplace/scope
+ * state check already confirmed a non-symlink install is present.
+ */
+declare function convertToSymlink(opts: InstallSkillOptions): Promise<InstallSkillResult>;
+/**
+ * Remove a skill/agent link from a workspace/user scope. Idempotent:
+ * succeeds when the link does not exist (no error).
+ *
+ * Tries the bare `<name>` path first (directory-based entries), then
+ * falls back to scanning the scope dir for a `<name>.<ext>` file (flat
+ * manifest entries, e.g. `CSharpExpert.agent.md`) — the caller doesn't
+ * necessarily still have the source repo entry to know which shape was
+ * installed (e.g. the repo may have been removed since).
+ */
+declare function uninstallSkillFromWorkspace(opts: {
+    repoId: string;
+    skillName: string;
+    workspaceDir: string;
+    kind?: EntryKind;
+    scope?: LinkScope;
+}): Promise<void>;
+/**
+ * Enumerate all skill/agent entries currently present in a workspace/user
+ * scope — both symlinked installs (`mode: "symlink"`/`"junction"`) AND
+ * real, non-symlink directories/files that already carry a valid
+ * manifest (`mode: "copy"`). Used by the UI's "Manage installed skills"
+ * view so it can show a real (copy-installed) entry as installed too —
+ * this is common for the user (global) scope, where many skills are
+ * placed by other tools/installers as plain copies rather than via this
+ * package's symlink-only install flow. `repoId` is `""` for `"copy"`
+ * entries since there's no symlink target to resolve it from; callers
+ * match these by name only. Returns an empty array when the scan
+ * directory doesn't exist.
+ */
+declare function listLinkedSkills(workspaceDir: string, kind?: EntryKind, scope?: LinkScope): Promise<LinkedSkill[]>;
+
+export { type EntryKind, type InstallSkillOptions, type InstallSkillResult, LinkError, type LinkMode, type LinkScope, type LinkedSkill, convertToSymlink, getPlatformHint, installSkillToWorkspace, listLinkedSkills, pickMode, resolveSkillLinkPath, resolveSkillTarget, resolveUserSkillLinkPath, uninstallSkillFromWorkspace };

package/dist/skill-linker.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Skill & Agent v2 — Client SkillLinker (M3, path-parity revision)
+ *
+ * SkillLinker exposes a skill/agent from the user's global repos
+ * (`~/.serviceme/repos/<repoId>/{skills,agents}/<name>/`) into either:
+ *
+ *   - a workspace, at `<workspace>/.github/{skills,agents}/<name>` —
+ *     the same path Copilot/Claude actually scan for `SKILL.md` /
+ *     `AGENT.md`, so linking here has real effect (see the v1 parity
+ *     note below); or
+ *   - the user's global scope, at `~/.agents/{skills,agents}/<name>`,
+ *     visible to every workspace.
+ *
+ * **v1 parity note**: an earlier revision linked into a private
+ * `<workspace>/.serviceme/skills/<repoId>/<name>` directory. That path
+ * is never scanned by the actual tooling, so installs were silently
+ * inert. The path was moved to match `.github/skills` (the same
+ * location the legacy v1 marketplace pipeline used). Because the link
+ * path is now flat (no `<repoId>` segment), only one repo's version of
+ * a given `<name>` can be linked into a given scope at a time.
+ *
+ * Platform behavior (per spec §11.8 — owner explicitly chose throw
+ * over silent copy fallback):
+ *
+ * | platform | default mode | on failure                  |
+ * |----------|--------------|-----------------------------|
+ * | macOS    | symlink      | throw + platform hint       |
+ * | Linux    | symlink      | throw + platform hint       |
+ * | Windows  | junction     | throw + platform hint       |
+ *
+ * Why junction first on Windows: NTFS junction doesn't require
+ * SeCreateSymbolicLinkPrivilege; it works for any user. The limit is
+ * the link target must be on a local NTFS volume. OneDrive / network
+ * shares sometimes fail; we surface that as a typed error so callers
+ * can decide whether to retry.
+ *
+ * @see docs/architecture/skill-agent-v2-repo.md §5.6 SkillLinker
+ * @see docs/architecture/skill-agent-v2-repo.md §11.8 (throw, not copy)
+ */
+type LinkMode = "symlink" | "junction" | "copy";
+/** Kind of artifact being linked. Mirrors `BridgeSkillKind`. */
+type EntryKind = "skill" | "agent";
+/**
+ * Which scope the link lives in:
+ *   - `"workspace"` (default) → `<workspaceDir>/.github/<kind>/<name>`
+ *   - `"user"` → `~/.agents/<kind>/<name>` (visible to every workspace)
+ */
+type LinkScope = "workspace" | "user";
+interface InstallSkillOptions {
+    repoId: string;
+    skillName: string;
+    workspaceDir: string;
+    /** Choose link mode explicitly. Defaults to platform-optimal. */
+    mode?: "auto" | LinkMode;
+    /** "skill" (default) or "agent". */
+    kind?: EntryKind;
+    /** "workspace" (default) or "user". */
+    scope?: LinkScope;
+    /**
+     * Pre-resolved absolute source path (from `SkillStore`), overriding
+     * the `<repoRoot>/{skills,agents}/<name>` formula in
+     * {@link resolveSkillTarget}. Required for repos with non-standard
+     * layouts — flat root (no `skills/` prefix), nested scope dirs
+     * (`skills/official/<name>`), or flat single-file agent manifests
+     * (`agents/<name>.agent.md`) — which the formula can't predict.
+     * When omitted, falls back to the formula (kept for callers that
+     * install a hand-authored skill without going through `SkillStore`).
+     */
+    sourcePath?: string;
+    /**
+     * True when `sourcePath` points at a single manifest FILE (e.g. a
+     * flat `<name>.agent.md`) rather than a directory. Determines the
+     * symlink type (file vs dir/junction) and the link's basename (the
+     * link mirrors the source file's name + extension, since Copilot/
+     * VS Code scan `.github/agents/<name>.agent.md` as a FILE).
+     */
+    sourceIsFile?: boolean;
+}
+interface InstallSkillResult {
+    mode: LinkMode;
+    linkPath: string;
+    targetPath: string;
+}
+/** Describes one symlink/junction currently present in a workspace/user scope. */
+interface LinkedSkill {
+    /**
+     * Repo id the link resolves to, parsed back out of the symlink
+     * target. Empty string when the target isn't under a recognizable
+     * `~/.serviceme/repos/<repoId>/...` path.
+     */
+    repoId: string;
+    skillName: string;
+    linkPath: string;
+    targetPath: string;
+    mode: LinkMode;
+    /** Which scope this link was found in — "workspace" or "user" (global). */
+    scope: LinkScope;
+}
+/**
+ * Sentinel error for link failures. Carries the chosen mode + platform
+ * hint so the UI can render an actionable message.
+ */
+declare class LinkError extends Error {
+    readonly mode: LinkMode;
+    readonly target: string;
+    readonly linkPath: string;
+    readonly platform: NodeJS.Platform;
+    readonly cause: unknown;
+    constructor(opts: {
+        mode: LinkMode;
+        target: string;
+        linkPath: string;
+        platform: NodeJS.Platform;
+        cause: unknown;
+    });
+    /** A user-facing hint for the platform that failed. */
+    hint(): string;
+}
+/** Choose the platform-optimal link mode. */
+declare function pickMode(platform?: NodeJS.Platform): LinkMode;
+/** A short hint string for the platform where the link failed. */
+declare function getPlatformHint(platform: NodeJS.Platform): string;
+/**
+ * Resolve the source path inside `~/.serviceme/repos/<repoId>/{skills,agents}/<name>`.
+ * Exported for callers that need to inspect the target without installing.
+ */
+declare function resolveSkillTarget(repoId: string, skillName: string, kind?: EntryKind): string;
+/**
+ * Resolve the workspace link path — `<workspaceDir>/.github/{skills,agents}/<name>` —
+ * the same directory Copilot/Claude actually scan.
+ */
+declare function resolveSkillLinkPath(workspaceDir: string, skillName: string, kind?: EntryKind): string;
+/**
+ * Resolve the user-scope link path — `~/.agents/{skills,agents}/<name>` —
+ * visible to every workspace.
+ */
+declare function resolveUserSkillLinkPath(skillName: string, kind?: EntryKind): string;
+/**
+ * Install a skill into a workspace by creating a link at the standard
+ * path. Throws `LinkError` on failure (no silent copy fallback per
+ * §11.8).
+ *
+ * Idempotent: if the correct link already exists, returns the existing
+ * record without touching the filesystem. If a *wrong* link exists at
+ * the target path, it is replaced.
+ */
+declare function installSkillToWorkspace(opts: InstallSkillOptions): Promise<InstallSkillResult>;
+/**
+ * Convert an existing, real (non-symlink) skill/agent directory at the
+ * standard scan path into a symlink pointing at the matching global
+ * repo entry. Refuses to run when there's nothing real to convert —
+ * callers should only surface this action when a marketplace/scope
+ * state check already confirmed a non-symlink install is present.
+ */
+declare function convertToSymlink(opts: InstallSkillOptions): Promise<InstallSkillResult>;
+/**
+ * Remove a skill/agent link from a workspace/user scope. Idempotent:
+ * succeeds when the link does not exist (no error).
+ *
+ * Tries the bare `<name>` path first (directory-based entries), then
+ * falls back to scanning the scope dir for a `<name>.<ext>` file (flat
+ * manifest entries, e.g. `CSharpExpert.agent.md`) — the caller doesn't
+ * necessarily still have the source repo entry to know which shape was
+ * installed (e.g. the repo may have been removed since).
+ */
+declare function uninstallSkillFromWorkspace(opts: {
+    repoId: string;
+    skillName: string;
+    workspaceDir: string;
+    kind?: EntryKind;
+    scope?: LinkScope;
+}): Promise<void>;
+/**
+ * Enumerate all skill/agent entries currently present in a workspace/user
+ * scope — both symlinked installs (`mode: "symlink"`/`"junction"`) AND
+ * real, non-symlink directories/files that already carry a valid
+ * manifest (`mode: "copy"`). Used by the UI's "Manage installed skills"
+ * view so it can show a real (copy-installed) entry as installed too —
+ * this is common for the user (global) scope, where many skills are
+ * placed by other tools/installers as plain copies rather than via this
+ * package's symlink-only install flow. `repoId` is `""` for `"copy"`
+ * entries since there's no symlink target to resolve it from; callers
+ * match these by name only. Returns an empty array when the scan
+ * directory doesn't exist.
+ */
+declare function listLinkedSkills(workspaceDir: string, kind?: EntryKind, scope?: LinkScope): Promise<LinkedSkill[]>;
+
+export { type EntryKind, type InstallSkillOptions, type InstallSkillResult, LinkError, type LinkMode, type LinkScope, type LinkedSkill, convertToSymlink, getPlatformHint, installSkillToWorkspace, listLinkedSkills, pickMode, resolveSkillLinkPath, resolveSkillTarget, resolveUserSkillLinkPath, uninstallSkillFromWorkspace };