skillfish 1.0.7 → 1.0.9

package/dist/lib/github.js

@@ -107,7 +107,7 @@ export async function fetchDefaultBranch(owner, repo) {
         if (!res.ok) {
             throw new GitHubApiError(`GitHub API returned status ${res.status}`);
         }
-        const data = await res.json();
+        const data = (await res.json());
         if (typeof data.default_branch !== 'string' || !data.default_branch) {
             throw new GitHubApiError('Repository metadata missing or invalid default_branch field');
         }
@@ -171,6 +171,42 @@ export async function fetchSkillMdContent(owner, repo, path, branch) {
         return null;
     }
 }
+/**
+ * Fetch the tree SHA for a repository branch.
+ * Used for update checks - compares stored SHA with current SHA.
+ *
+ * @throws {RepoNotFoundError} When the repository is not found
+ * @throws {RateLimitError} When GitHub API rate limit is exceeded
+ * @throws {NetworkError} On network errors
+ * @throws {GitHubApiError} When the API response format is unexpected
+ */
+export async function fetchTreeSha(owner, repo, branch) {
+    const headers = { 'User-Agent': 'skillfish' };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
+    try {
+        const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}`;
+        const res = await fetchWithRetry(url, { headers, signal: controller.signal });
+        checkRateLimit(res);
+        if (res.status === 404) {
+            throw new RepoNotFoundError(owner, repo);
+        }
+        if (!res.ok) {
+            throw new GitHubApiError(`GitHub API returned status ${res.status}`);
+        }
+        const data = (await res.json());
+        if (typeof data.sha !== 'string' || !/^[a-f0-9]{40}$/.test(data.sha)) {
+            throw new GitHubApiError('Invalid or missing sha field in tree response');
+        }
+        return data.sha;
+    }
+    catch (err) {
+        wrapApiError(err);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
 /**
  * Find all SKILL.md files in a GitHub repository.
  * Fetches the default branch, then searches for skills on that branch.
@@ -199,7 +235,8 @@ export async function findAllSkillMdFiles(owner, repo) {
             throw new GitHubApiError('Unexpected response format from GitHub API.');
         }
         const paths = extractSkillPaths(rawData, SKILL_FILENAME);
-        return { paths, branch };
+        const sha = rawData.sha ?? '';
+        return { paths, branch, sha };
     }
     catch (err) {
         wrapApiError(err);

package/dist/lib/installer.d.ts

@@ -4,16 +4,16 @@
  */
 import type { Agent } from './agents.js';
 export interface InstallResult {
-    installed: Array<{
+    installed: {
         skill: string;
         agent: string;
         path: string;
-    }>;
-    skipped: Array<{
+    }[];
+    skipped: {
         skill: string;
         agent: string;
         reason: string;
-    }>;
+    }[];
     warnings: string[];
     failed: boolean;
     failureReason?: string;
@@ -21,8 +21,10 @@ export interface InstallResult {
 export interface InstallOptions {
     force: boolean;
     baseDir: string;
-    /** Branch to clone from. If not specified, degit will use default branch detection. */
+    /** Branch to clone from. If not specified, giget will use the repository's default branch. */
     branch?: string;
+    /** Tree SHA for manifest tracking. If provided, .skillfish.json will be written. */
+    sha?: string;
 }
 export interface CopyResult {
     warnings: string[];

package/dist/lib/installer.js

@@ -2,22 +2,23 @@
  * Skill installation logic.
  * Handles downloading, validating, and installing skills to agent directories.
  */
-import { existsSync, mkdirSync, cpSync, rmSync, lstatSync, readdirSync, } from 'fs';
+import { existsSync, mkdirSync, cpSync, rmSync, lstatSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
-import degit from 'degit';
+import { downloadTemplate } from 'giget';
 import { SKILL_FILENAME } from './github.js';
+import { writeManifest, MANIFEST_VERSION } from './manifest.js';
 /**
- * Validates a branch name for safe use in degit paths.
+ * Validates a branch name for safe use in giget source strings.
  * Git branch names can contain alphanumerics, dots, hyphens, underscores, and slashes.
- * We explicitly reject '#' which is used as a delimiter in degit syntax.
+ * We explicitly reject '#' which is used as a delimiter in giget syntax.
  */
 function isValidBranchName(branch) {
     if (!branch || branch.length > 255)
         return false;
     // Allow alphanumerics, dots, hyphens, underscores, and slashes (for feature branches)
-    // Reject anything else, especially '#' which would break degit parsing
+    // Reject anything else, especially '#' which would break giget parsing
     return /^[\w./-]+$/.test(branch) && !branch.includes('#');
 }
 // === Error Types ===
@@ -98,24 +99,28 @@ export async function installSkill(owner, repo, skillPath, skillName, agents, op
         warnings: [],
         failed: false,
     };
-    const { force, baseDir, branch } = options;
+    const { force, baseDir, branch, sha } = options;
     const tmpDir = join(homedir(), '.cache', 'skillfish', `${owner}-${repo}-${randomUUID()}`);
     mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
     try {
-        // Download skill
-        // Build degit path: owner/repo[/subpath][#branch]
+        // Download skill using giget (tarball-based, works reliably on all repo sizes)
+        // Build giget source: github:owner/repo[/subpath][#branch]
         const downloadPath = skillPath === SKILL_FILENAME ? '' : skillPath;
-        let degitPath = downloadPath ? `${owner}/${repo}/${downloadPath}` : `${owner}/${repo}`;
+        let source = downloadPath
+            ? `github:${owner}/${repo}/${downloadPath}`
+            : `github:${owner}/${repo}`;
         // Append branch if specified (critical for repos with non-standard default branches like 'canary')
         // Validate branch name to prevent injection attacks via malformed branch names
         if (branch) {
             if (!isValidBranchName(branch)) {
                 throw new Error(`Invalid branch name: ${branch}`);
             }
-            degitPath = `${degitPath}#${branch}`;
+            source = `${source}#${branch}`;
         }
-        const emitter = degit(degitPath, { cache: false, force: true });
-        await emitter.clone(tmpDir);
+        await downloadTemplate(source, {
+            dir: tmpDir,
+            forceClean: true,
+        });
         // Validate download
         const skillMdPath = join(tmpDir, SKILL_FILENAME);
         if (!existsSync(skillMdPath)) {
@@ -140,6 +145,18 @@ export async function installSkill(owner, repo, skillPath, skillName, agents, op
             // Use safe copy to skip symlinks (security: prevents symlink attacks)
             const copyResult = safeCopyDir(tmpDir, destDir);
             result.warnings.push(...copyResult.warnings.map((w) => `${skillName}: ${w}`));
+            // Write manifest for tracking if SHA is provided
+            if (sha && branch) {
+                const manifest = {
+                    version: MANIFEST_VERSION,
+                    owner,
+                    repo,
+                    path: skillPath === SKILL_FILENAME ? '.' : skillPath,
+                    branch,
+                    sha,
+                };
+                writeManifest(destDir, manifest);
+            }
             result.installed.push({
                 skill: skillName,
                 agent: agent.name,
@@ -154,13 +171,8 @@ export async function installSkill(owner, repo, skillPath, skillName, agents, op
         }
         else {
             const errMsg = err instanceof Error ? err.message : String(err);
-            // Provide more helpful error messages for common degit failures
-            // Match "could not find commit hash for HEAD" or "could not find commit hash for <branch>"
-            if (errMsg.includes('could not find commit hash')) {
-                const branchInfo = branch ? ` (branch: ${branch})` : '';
-                result.failureReason = `Could not clone repository. The branch or path may not exist, or there may be a network issue. Tried: ${owner}/${repo}${skillPath !== SKILL_FILENAME ? `/${skillPath}` : ''}${branchInfo}`;
-            }
-            else if (errMsg.includes('404')) {
+            // Provide more helpful error messages for common failures
+            if (errMsg.includes('404') || errMsg.includes('Not Found')) {
                 result.failureReason = `Repository or path not found: ${owner}/${repo}${skillPath !== SKILL_FILENAME ? `/${skillPath}` : ''}`;
             }
             else {

package/dist/lib/manifest.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Manifest handling for skill tracking.
+ * Each installed skill has a .skillfish.json file that tracks its origin.
+ */
+export declare const MANIFEST_FILENAME = ".skillfish.json";
+export declare const MANIFEST_VERSION = 1;
+/**
+ * Manifest schema for tracking installed skills.
+ * Stored in .skillfish.json within each skill directory.
+ */
+export interface SkillManifest {
+    /** Schema version for future migrations */
+    version: 1;
+    /** GitHub repository owner */
+    owner: string;
+    /** GitHub repository name */
+    repo: string;
+    /** Path within repo (e.g., "skills/my-skill" or ".") */
+    path: string;
+    /** Branch at install time */
+    branch: string;
+    /** Tree SHA at install time (from git/trees response) */
+    sha: string;
+}
+/**
+ * Read manifest from a skill directory.
+ *
+ * @param skillDir - Path to the skill directory
+ * @returns Parsed manifest or null if not found/invalid
+ */
+export declare function readManifest(skillDir: string): SkillManifest | null;
+/**
+ * Write manifest to a skill directory.
+ *
+ * @param skillDir - Path to the skill directory
+ * @param manifest - Manifest data to write
+ */
+export declare function writeManifest(skillDir: string, manifest: SkillManifest): void;
+/**
+ * Check if a skill directory has a manifest.
+ *
+ * @param skillDir - Path to the skill directory
+ * @returns true if manifest exists
+ */
+export declare function hasManifest(skillDir: string): boolean;

package/dist/lib/manifest.js

@@ -0,0 +1,100 @@
+/**
+ * Manifest handling for skill tracking.
+ * Each installed skill has a .skillfish.json file that tracks its origin.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { isValidName } from './constants.js';
+import { isValidPath } from '../utils.js';
+// === Constants ===
+export const MANIFEST_FILENAME = '.skillfish.json';
+export const MANIFEST_VERSION = 1;
+/** Git SHA format: 40 hexadecimal characters */
+const SHA_PATTERN = /^[a-f0-9]{40}$/;
+/** Git branch name pattern (alphanumerics, dots, hyphens, underscores, slashes) */
+const BRANCH_PATTERN = /^[\w./-]+$/;
+// === Functions ===
+/**
+ * Read manifest from a skill directory.
+ *
+ * @param skillDir - Path to the skill directory
+ * @returns Parsed manifest or null if not found/invalid
+ */
+export function readManifest(skillDir) {
+    const manifestPath = join(skillDir, MANIFEST_FILENAME);
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(manifestPath, 'utf-8');
+        const data = JSON.parse(content);
+        // Validate manifest structure
+        if (!isValidManifest(data)) {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        // JSON parse error or file read error
+        return null;
+    }
+}
+/**
+ * Write manifest to a skill directory.
+ *
+ * @param skillDir - Path to the skill directory
+ * @param manifest - Manifest data to write
+ */
+export function writeManifest(skillDir, manifest) {
+    const manifestPath = join(skillDir, MANIFEST_FILENAME);
+    const content = JSON.stringify(manifest, null, 2);
+    writeFileSync(manifestPath, content, 'utf-8');
+}
+/**
+ * Check if a skill directory has a manifest.
+ *
+ * @param skillDir - Path to the skill directory
+ * @returns true if manifest exists
+ */
+export function hasManifest(skillDir) {
+    return existsSync(join(skillDir, MANIFEST_FILENAME));
+}
+/**
+ * Type guard to validate manifest structure and content.
+ * Validates both field types and content to prevent tampered manifests
+ * from causing unintended API requests or file operations.
+ */
+function isValidManifest(data) {
+    if (typeof data !== 'object' || data === null) {
+        return false;
+    }
+    const obj = data;
+    // Check types first
+    if (obj.version !== MANIFEST_VERSION ||
+        typeof obj.owner !== 'string' ||
+        typeof obj.repo !== 'string' ||
+        typeof obj.path !== 'string' ||
+        typeof obj.branch !== 'string' ||
+        typeof obj.sha !== 'string') {
+        return false;
+    }
+    // Validate content to prevent tampered manifests
+    const { owner, repo, path, branch, sha } = obj;
+    // Owner and repo must be valid GitHub names
+    if (!isValidName(owner) || !isValidName(repo)) {
+        return false;
+    }
+    // Path must be safe (no traversal) - "." is valid for root
+    if (path !== '.' && !isValidPath(path)) {
+        return false;
+    }
+    // Branch must match git branch pattern
+    if (!BRANCH_PATTERN.test(branch) || branch.length > 255) {
+        return false;
+    }
+    // SHA must be valid git SHA format (40 hex chars)
+    if (!SHA_PATTERN.test(sha)) {
+        return false;
+    }
+    return true;
+}

package/dist/utils.d.ts

@@ -10,23 +10,23 @@ export declare function isValidPath(pathStr: string): boolean;
 /**
  * Type for GitHub tree API item.
  */
-export type GitTreeItem = {
+export interface GitTreeItem {
     path: string;
     type: string;
     mode?: string;
     sha?: string;
     size?: number;
     url?: string;
-};
+}
 /**
  * Type for GitHub tree API response.
  */
-export type GitTreeResponse = {
+export interface GitTreeResponse {
     tree?: GitTreeItem[];
     sha?: string;
     url?: string;
     truncated?: boolean;
-};
+}
 /**
  * Type guard for GitHub tree API response.
  * Validates the response structure at runtime.
@@ -94,11 +94,11 @@ export interface BaseJsonOutput {
  */
 export interface AddJsonOutput extends BaseJsonOutput {
     installed: InstalledSkill[];
-    skipped: Array<{
+    skipped: {
         skill: string;
         agent: string;
         reason: string;
-    }>;
+    }[];
     skills_found?: string[];
 }
 /**
@@ -114,6 +114,25 @@ export interface ListJsonOutput extends BaseJsonOutput {
 export interface RemoveJsonOutput extends BaseJsonOutput {
     removed: InstalledSkill[];
 }
+/**
+ * Outdated skill information for update command.
+ */
+export interface OutdatedSkill {
+    skill: string;
+    agent: string;
+    path: string;
+    location: 'global' | 'project';
+    localSha: string;
+    remoteSha: string;
+    source: string;
+}
+/**
+ * JSON output for the `update` command.
+ */
+export interface UpdateJsonOutput extends BaseJsonOutput {
+    outdated: OutdatedSkill[];
+    updated: InstalledSkill[];
+}
 /** @deprecated Use AddJsonOutput instead */
 export type JsonOutput = AddJsonOutput;
 /**

package/dist/utils.js

@@ -86,9 +86,7 @@ export function deriveSkillName(skillPath, repoName) {
  * "my_cool_skill" → "My Cool Skill"
  */
 export function toTitleCase(str) {
-    return str
-        .replace(/[-_]/g, ' ')
-        .replace(/\b\w/g, char => char.toUpperCase());
+    return str.replace(/[-_]/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase());
 }
 /**
  * Truncate text to a maximum length, adding ellipsis if needed.
@@ -105,14 +103,14 @@ export function extractSkillPaths(data, skillFilename = 'SKILL.md') {
     if (!data.tree)
         return [];
     return data.tree
-        .filter(item => item.type === 'blob' && item.path.endsWith(skillFilename))
-        .map(item => item.path);
+        .filter((item) => item.type === 'blob' && item.path.endsWith(skillFilename))
+        .map((item) => item.path);
 }
 /**
  * Sleep for a specified duration.
  */
 export function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
  * Process items with bounded concurrency.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillfish",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Install AI agent skills from GitHub with a single command",
   "type": "module",
   "bin": {
@@ -24,9 +24,15 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run lint && npm test && npm run build",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky"
   },
   "keywords": [
     "cli",
@@ -54,15 +60,38 @@
   "author": "Graeme Knox",
   "license": "AGPL-3.0",
   "homepage": "https://skill.fish",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/knoxgraeme"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "commander": "^14.0.2",
-    "degit": "^2.8.4",
+    "giget": "^3.1.1",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "@types/node": "^20.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
     "typescript": "^5.4.0",
+    "typescript-eslint": "^8.53.1",
     "vitest": "^4.0.17"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,yml,yaml}": [
+      "prettier --write"
+    ]
   }
 }