@devdogfish/jawfish 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./jawfish-logo-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="./jawfish-logo-light.png">
+    <img alt="Jawfish - A minimal package manager for your AI skills." src="./jawfish-logo-light.png" height="320" style="margin-bottom: 20px;">
+  </picture>
+</div>
+
+## What Is Jawfish?
+
+Jawfish is a small package manager for reusable agentics:
+
+1. Keep skills, prompts, and agents in one content library.
+2. Install them globally or into a project.
+3. Update them when upstream changes.
+
+## Quick Start
+
+Install:
+
+```sh
+bun install --global @devdogfish/jawfish
+```
+
+Configure:
+
+```json
+{
+  "allowedTools": ["codex"],
+  "defaultTool": "codex",
+  "contentLibrary": "git@github.com:you/agentics.git"
+}
+```
+
+Save it at `~/.jawfish/config.json`.
+
+Add a skill:
+
+```sh
+jawfish add handoff
+```
+
+Install everything from the manifest:
+
+```sh
+jawfish install
+```
+
+Update later:
+
+```sh
+jawfish update
+```
+
+## How It Works
+
+Jawfish reads from one content library and writes tool-native files into the
+current project or your global tool config.
+
+Project installs are tracked in `jawfish.json`. Global installs are tracked in
+`~/.jawfish/jawfish.json`.
+
+## Commands
+
+| Command                 | What it does                         |
+| ----------------------- | ------------------------------------ |
+| `jawfish add <name>`    | Install from your library            |
+| `jawfish add <source>`  | Import from a URL or local file      |
+| `jawfish install`       | Reinstall everything in the manifest |
+| `jawfish update [name]` | Pull upstream changes                |
+| `jawfish remove <name>` | Remove a managed install             |
+
+Add `--global` to target your global tool config instead of the current
+project.
+
+Jawfish currently supports `codex`, `claude-code`, and `hermes`.
+
+Project installs go into `.codex/`, `.claude/`, or `.hermes/`. Global Codex
+installs go into:
+
+```sh
+~/.codex/skills
+~/.codex/agents
+~/.codex/prompts
+```
+
+## Develop
+
+```sh
+bun install
+bun run typecheck
+bun run test
+```

package/dist/config.js

@@ -0,0 +1,72 @@
+import { cancel, isCancel, select } from "@clack/prompts";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { errorHasCode, errorMessage } from "./errors.js";
+import { supportedTools } from "./tool-adapters.js";
+export const defaultAllowedTools = supportedTools;
+export function jawfishHome(env = process.env) {
+    return env.JAWFISH_HOME ?? join(homedir(), ".jawfish");
+}
+export function configPath(home = jawfishHome()) {
+    return join(home, "config.json");
+}
+export async function loadConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const home = jawfishHome(env);
+    const filePath = configPath(home);
+    const existing = await readConfig(filePath);
+    const config = {
+        ...existing,
+        allowedTools: existing.allowedTools ?? [...defaultAllowedTools],
+    };
+    let changed = existing.allowedTools === undefined;
+    if (config.contentLibrary === undefined && env.JAWFISH_CONTENT_LIBRARY) {
+        config.contentLibrary = env.JAWFISH_CONTENT_LIBRARY;
+        changed = true;
+    }
+    if (config.defaultTool === undefined) {
+        config.defaultTool = await chooseDefaultTool(config.allowedTools, options, env);
+        changed = true;
+    }
+    if (changed) {
+        await writeConfig(filePath, config);
+    }
+    return config;
+}
+export async function promptForTool(allowedTools) {
+    const selected = await select({
+        message: "Select default tool",
+        options: allowedTools.map((tool) => ({ label: tool, value: tool })),
+    });
+    if (isCancel(selected)) {
+        cancel("No tool selected");
+        throw new Error("No tool selected");
+    }
+    return selected;
+}
+async function chooseDefaultTool(allowedTools, options, env) {
+    const envDefault = env.JAWFISH_DEFAULT_TOOL;
+    if (envDefault !== undefined) {
+        if (!allowedTools.includes(envDefault)) {
+            throw new Error(`Default tool is not allowed: ${envDefault}`);
+        }
+        return envDefault;
+    }
+    return (options.promptForDefaultTool ?? promptForTool)(allowedTools);
+}
+async function readConfig(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (errorHasCode(error, "ENOENT")) {
+            return {};
+        }
+        throw new Error(`Invalid config at ${path}: ${errorMessage(error)}`);
+    }
+}
+async function writeConfig(path, config) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`);
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function errorHasCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}

package/dist/main.js

@@ -0,0 +1,1011 @@
+#!/usr/bin/env -S node --experimental-strip-types
+import { cancel, isCancel, select } from "@clack/prompts";
+import { spawn } from "node:child_process";
+import { cp, mkdir, mkdtemp, readdir, readFile, realpath, rm, stat, writeFile, } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertSupportedTool, destinationPath, supportedTools, typeFolder, } from "./tool-adapters.js";
+const version = "0.1.0";
+const catalogFile = "catalog.json";
+const indexCatalogFile = "index.json";
+const projectManifestFile = "jawfish.json";
+const managedMarkerFile = ".jawfish-managed.json";
+const libraryIgnoreEntries = ["config.json", "jawfish.json"];
+const defaultTools = supportedTools;
+const agenticTypes = [
+    "skill",
+    "agent",
+    "prompt",
+];
+const commandSpecs = {
+    add: {
+        description: "Install an agentic from the library, or import a URL/local path.",
+        summary: "Install or import an agentic",
+        usage: "jawfish add [options] <name|source>",
+        options: [
+            "-g, --global    Install globally",
+            "--name <name>   Override imported package name",
+            "-h, --help      Show help",
+        ],
+    },
+    install: {
+        description: "Materialize manifest jawfish into tool-native directories.",
+        summary: "Materialize manifest jawfish",
+        usage: "jawfish install [options]",
+        options: [
+            "-g, --global    Install global manifest",
+            "-h, --help      Show help",
+        ],
+    },
+    update: {
+        description: "Refresh one or all upstream-backed jawfish.",
+        summary: "Update upstream-backed jawfish",
+        usage: "jawfish update [options] [name]",
+        options: [
+            "-g, --global    Reinstall global manifest if already installed",
+            "-F, --force     Replace dirty package contents",
+            "-h, --help      Show help",
+        ],
+    },
+    remove: {
+        description: "Remove installed managed jawfish.",
+        summary: "Remove installed jawfish",
+        usage: "jawfish remove [options] <name>",
+        options: [
+            "-g, --global    Remove global install",
+            "-h, --help      Show help",
+        ],
+    },
+};
+const commandNames = Object.keys(commandSpecs);
+export async function promptForTool(allowedTools) {
+    const selected = await select({
+        message: "Select default tool",
+        options: allowedTools.map((tool) => ({ label: tool, value: tool })),
+    });
+    if (isCancel(selected)) {
+        cancel("No tool selected");
+        process.exitCode = 1;
+        return "";
+    }
+    return selected;
+}
+export async function promptForAgenticType(packagePath) {
+    const selected = await select({
+        message: `Select agentic type for ${packagePath}`,
+        options: agenticTypes.map((type) => ({ label: type, value: type })),
+    });
+    if (isCancel(selected)) {
+        cancel("No agentic type selected");
+        throw new Error("No agentic type selected");
+    }
+    return selected;
+}
+export async function run(argv) {
+    const [command, ...args] = argv;
+    try {
+        if (command === undefined || isHelp(command)) {
+            printRootHelp();
+            return 0;
+        }
+        if (command === "--version" || command === "-v") {
+            console.log(version);
+            return 0;
+        }
+        if (!isCommandName(command)) {
+            console.error(`Unknown command: ${command}`);
+            console.error("Run jawfish --help for usage.");
+            return 1;
+        }
+        const parsed = parseArgs(args);
+        if (parsed.help) {
+            printCommandHelp(command);
+            return 0;
+        }
+        switch (command) {
+            case "add":
+                return await addCommand(parsed);
+            case "install":
+                return await installCommand(parsed);
+            case "remove":
+                return await removeCommand(parsed);
+            case "update":
+                return await updateCommand(parsed);
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+async function addCommand(args) {
+    const source = args.positionals[0];
+    if (source === undefined) {
+        console.error("Usage: jawfish add [options] <name|source>");
+        return 1;
+    }
+    const config = await loadConfig();
+    const libraryDir = await resolveContentLibrary(config);
+    const catalog = await readCatalog(libraryDir);
+    const scope = getScope(args);
+    if (catalogHasAgentic(catalog, source)) {
+        const tool = await installOne(libraryDir, catalog, source, scope, config);
+        console.log(`Added ${source} to ${scope}`);
+        printCatalogEntry(source, catalog.jawfish[source], tool);
+        return 0;
+    }
+    const imported = await importPackage(libraryDir, catalog, source, args.name);
+    await writeCatalog(libraryDir, catalog);
+    if (!(await pushLibraryChanges(libraryDir, `add ${imported}`))) {
+        return 1;
+    }
+    await installOne(libraryDir, catalog, imported, scope, config);
+    console.log(`Added ${imported} to ${scope}`);
+    return 0;
+}
+async function installCommand(args) {
+    const config = await loadConfig();
+    const libraryDir = await resolveContentLibrary(config);
+    await syncLibrary(libraryDir);
+    const catalog = await readCatalog(libraryDir);
+    const scope = getScope(args);
+    const manifest = await readManifest(scope);
+    const names = Object.keys(manifest.jawfish);
+    for (const name of names) {
+        const tool = manifest.jawfish[name].tool;
+        assertConfiguredTool(config, tool);
+        await materialize(libraryDir, catalog, name, scope, tool);
+    }
+    console.log(`Installed ${names.length} jawfish to ${scope}`);
+    return 0;
+}
+async function removeCommand(args) {
+    const name = args.positionals[0];
+    if (name === undefined) {
+        console.error("Usage: jawfish remove [options] <name>");
+        return 1;
+    }
+    const config = await loadConfig();
+    const libraryDir = await resolveContentLibrary(config);
+    const catalog = await readCatalog(libraryDir);
+    const scope = getScope(args);
+    const manifest = await readManifest(scope);
+    const manifestEntry = manifest.jawfish[name];
+    const catalogEntry = catalog.jawfish[name];
+    if (manifestEntry !== undefined && catalogEntry !== undefined) {
+        assertConfiguredTool(config, manifestEntry.tool);
+        await removeMaterialized(name, catalogEntry.type, scope, manifestEntry.tool);
+    }
+    delete manifest.jawfish[name];
+    await writeManifest(scope, manifest);
+    console.log(`Removed ${name} from ${scope}`);
+    return 0;
+}
+async function updateCommand(args) {
+    const config = await loadConfig();
+    const libraryDir = await resolveContentLibrary(config);
+    const catalog = await readCatalog(libraryDir);
+    const name = args.positionals[0];
+    const reinstallScope = getScope(args);
+    if (name !== undefined) {
+        await updatePackage(libraryDir, catalog, name, args.force);
+        await writeCatalog(libraryDir, catalog);
+        if (!(await pushLibraryChanges(libraryDir, `update ${name}`))) {
+            return 1;
+        }
+        await reinstallInScopeIfPresent(libraryDir, catalog, name, reinstallScope, config);
+        console.log(`Updated ${name}`);
+        return 0;
+    }
+    const summary = await updateAllPackages(libraryDir, catalog, args.force);
+    if (summary.failed.length === 0 && summary.updated.length > 0) {
+        await writeCatalog(libraryDir, catalog);
+        if (!(await pushLibraryChanges(libraryDir, "update jawfish"))) {
+            printBulkUpdateSummary(summary);
+            return 1;
+        }
+        await Promise.all(summary.updated.map((updatedName) => reinstallInScopeIfPresent(libraryDir, catalog, updatedName, reinstallScope, config)));
+    }
+    printBulkUpdateSummary(summary);
+    return summary.failed.length > 0 ? 1 : 0;
+}
+async function installOne(libraryDir, catalog, name, scope, config) {
+    const tool = await resolveTool(config);
+    await materialize(libraryDir, catalog, name, scope, tool);
+    const manifest = await readManifest(scope);
+    manifest.jawfish[name] = { tool };
+    await writeManifest(scope, manifest);
+    return tool;
+}
+async function materialize(libraryDir, catalog, name, scope, tool) {
+    const entry = catalog.jawfish[name];
+    if (entry === undefined) {
+        throw new Error(`Unknown agentic: ${name}`);
+    }
+    const sourcePath = resolveInside(libraryDir, entry.path);
+    const destination = destinationPath(name, entry.type, scope, tool, toolPaths());
+    const managedFiles = await managedFileSet(destination);
+    const sourceFiles = await packageFiles(sourcePath);
+    await assertNoUnmanagedConflicts(destination, sourceFiles, managedFiles);
+    await mkdir(destination, { recursive: true });
+    await removeStaleManagedFiles(destination, sourceFiles, managedFiles);
+    await copyPackageFiles(destination, sourceFiles);
+    await writeJson(join(destination, managedMarkerFile), {
+        files: sourceFiles.map((file) => file.relativePath).sort(),
+        name,
+        tool,
+        type: entry.type,
+    });
+}
+async function assertNoUnmanagedConflicts(destination, sourceFiles, managedFiles) {
+    for (const sourceFile of sourceFiles) {
+        const installedPath = join(destination, sourceFile.relativePath);
+        if ((await exists(installedPath)) &&
+            !managedFiles.has(sourceFile.relativePath)) {
+            throw new Error(`Refusing to overwrite unmanaged destination file: ${installedPath}\n` +
+                "Remove it or move it aside, then retry.");
+        }
+    }
+}
+async function removeStaleManagedFiles(destination, sourceFiles, managedFiles) {
+    const sourceFileNames = new Set(sourceFiles.map((file) => file.relativePath));
+    for (const managedFile of managedFiles) {
+        if (!sourceFileNames.has(managedFile)) {
+            const installedPath = join(destination, managedFile);
+            await rm(installedPath, { force: true });
+            await removeEmptyParents(dirname(installedPath), destination);
+        }
+    }
+}
+async function copyPackageFiles(destination, sourceFiles) {
+    for (const sourceFile of sourceFiles) {
+        const installedPath = join(destination, sourceFile.relativePath);
+        await mkdir(dirname(installedPath), { recursive: true });
+        await cp(sourceFile.path, installedPath);
+    }
+}
+async function removeMaterialized(name, type, scope, tool) {
+    const destination = destinationPath(name, type, scope, tool, toolPaths());
+    await removeManagedDestination(destination);
+}
+async function managedFileSet(destination) {
+    if (!(await exists(destination))) {
+        return new Set();
+    }
+    const markerPath = join(destination, managedMarkerFile);
+    if (!(await exists(markerPath))) {
+        throw new Error(`Refusing to overwrite unmanaged destination: ${destination}\n` +
+            "Remove it or move it aside, then retry.");
+    }
+    const marker = JSON.parse(await readFile(markerPath, "utf8"));
+    if (Array.isArray(marker.files)) {
+        return new Set(marker.files);
+    }
+    return new Set(await installedFiles(destination));
+}
+async function removeManagedDestination(destination) {
+    if (!(await exists(destination))) {
+        return;
+    }
+    const markerPath = join(destination, managedMarkerFile);
+    if (!(await exists(markerPath))) {
+        return;
+    }
+    for (const managedFile of await managedFileSet(destination)) {
+        const installedPath = join(destination, managedFile);
+        await rm(installedPath, { force: true });
+        await removeEmptyParents(dirname(installedPath), destination);
+    }
+    await rm(markerPath, { force: true });
+    await removeEmptyParents(destination, destination);
+}
+async function packageFiles(sourcePath) {
+    const sourceStat = await stat(sourcePath);
+    if (!sourceStat.isDirectory()) {
+        return [{ path: sourcePath, relativePath: basename(sourcePath) }];
+    }
+    return directoryFiles(sourcePath, sourcePath);
+}
+async function installedFiles(destination) {
+    return (await directoryFiles(destination, destination))
+        .map((file) => file.relativePath)
+        .filter((file) => file !== managedMarkerFile);
+}
+async function directoryFiles(root, current) {
+    const entries = await readdir(current, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const path = join(current, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await directoryFiles(root, path)));
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push({
+                path,
+                relativePath: relative(root, path),
+            });
+        }
+    }
+    return files;
+}
+async function removeEmptyParents(start, root) {
+    const resolvedRoot = resolve(root);
+    let current = resolve(start);
+    while (current === resolvedRoot || current.startsWith(`${resolvedRoot}/`)) {
+        if (!(await exists(current))) {
+            current = dirname(current);
+            continue;
+        }
+        if ((await readdir(current)).length > 0) {
+            return;
+        }
+        await rm(current, { force: true, recursive: true });
+        if (current === resolvedRoot) {
+            return;
+        }
+        current = dirname(current);
+    }
+}
+async function importPackage(libraryDir, catalog, source, nameOverride) {
+    const acquired = await acquireSource(source);
+    const name = nameOverride ?? acquired.inferredName;
+    if (catalogHasAgentic(catalog, name)) {
+        throw new Error(`Agentic already exists in catalog: ${name}`);
+    }
+    const type = await inferType(acquired.packagePath, acquired.entryFile);
+    const packagePath = join(typeFolder(type), name);
+    const destination = resolveInside(libraryDir, packagePath);
+    await rm(destination, { force: true, recursive: true });
+    await mkdir(dirname(destination), { recursive: true });
+    await cp(acquired.packagePath, destination, { recursive: true });
+    catalog.jawfish[name] = {
+        description: "",
+        path: packagePath,
+        type,
+        upstream: source,
+    };
+    return name;
+}
+async function acquireSource(source) {
+    return isUrl(source) ? acquireUrlSource(source) : acquireLocalSource(source);
+}
+async function acquireLocalSource(source) {
+    const localPath = resolve(process.cwd(), source);
+    const sourceStat = await stat(localPath);
+    const packagePath = sourceStat.isDirectory() ? localPath : dirname(localPath);
+    return {
+        entryFile: sourceStat.isDirectory() ? undefined : localPath,
+        inferredName: inferPackageName(packagePath),
+        packagePath,
+    };
+}
+async function acquireUrlSource(source) {
+    const tempDir = await mkdtemp(join(tmpdir(), "jawfish-source-"));
+    const url = new URL(source);
+    const fileName = basename(url.pathname) || "agentic.md";
+    const sourceResponse = await fetchUrl(source);
+    if (isDirectoryListing(sourceResponse)) {
+        await downloadUrlDirectory(source, tempDir, sourceResponse.links);
+        return {
+            inferredName: inferUrlPackageName(url.pathname),
+            packagePath: tempDir,
+        };
+    }
+    const parentUrl = new URL(".", source).toString();
+    const parentResponse = await fetchUrl(parentUrl, false);
+    const filePath = join(tempDir, fileName);
+    if (parentResponse !== undefined && isDirectoryListing(parentResponse)) {
+        await downloadUrlDirectory(parentUrl, tempDir, parentResponse.links);
+    }
+    else {
+        await writeFile(filePath, sourceResponse.body);
+    }
+    return {
+        entryFile: filePath,
+        inferredName: inferUrlPackageName(dirname(url.pathname)) || inferPackageName(fileName),
+        packagePath: tempDir,
+    };
+}
+async function fetchUrl(source, throwOnMissing = true) {
+    const response = await fetch(source);
+    if (!response.ok) {
+        if (!throwOnMissing && response.status === 404) {
+            return undefined;
+        }
+        throw new Error(`Failed to fetch ${source}: ${response.status} ${response.statusText}`);
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    const contentType = response.headers.get("content-type") ?? "";
+    return {
+        body,
+        contentType,
+        links: parseHtmlLinks(body.toString("utf8")),
+    };
+}
+function isDirectoryListing(response) {
+    return (response.contentType.includes("text/html") && response.links.length > 0);
+}
+async function downloadUrlDirectory(source, destination, directoryLinks) {
+    const directoryUrl = source.endsWith("/") ? source : `${source}/`;
+    const links = directoryLinks ?? (await fetchUrl(directoryUrl)).links;
+    await mkdir(destination, { recursive: true });
+    for (const link of links) {
+        const childUrl = new URL(link, directoryUrl);
+        if (!isImportableChildUrl(childUrl, directoryUrl)) {
+            continue;
+        }
+        const childName = basename(childUrl.pathname.replace(/\/$/u, ""));
+        if (childName === "") {
+            continue;
+        }
+        const childResponse = await fetchUrl(childUrl.toString());
+        const childDestination = join(destination, childName);
+        if (isDirectoryListing(childResponse)) {
+            await downloadUrlDirectory(childUrl.toString(), childDestination, childResponse.links);
+            continue;
+        }
+        await writeFile(childDestination, childResponse.body);
+    }
+}
+function parseHtmlLinks(html) {
+    return [...html.matchAll(/href\s*=\s*["']([^"']+)["']/giu)]
+        .map((match) => match[1])
+        .filter((href) => href !== "" && !href.startsWith("#") && !href.startsWith("?"));
+}
+function isAgenticType(value) {
+    return agenticTypes.includes(value);
+}
+function isImportableChildUrl(childUrl, parentUrl) {
+    const parent = new URL(parentUrl);
+    return (childUrl.origin === parent.origin &&
+        childUrl.pathname !== parent.pathname &&
+        childUrl.pathname.startsWith(parent.pathname) &&
+        !childUrl.pathname.includes(".."));
+}
+function inferUrlPackageName(pathname) {
+    return basename(pathname.replace(/\/$/u, ""));
+}
+async function updatePackage(libraryDir, catalog, name, force) {
+    const entry = catalog.jawfish[name];
+    if (entry === undefined) {
+        throw new Error(`Unknown agentic: ${name}`);
+    }
+    if (entry.upstream === undefined) {
+        throw new Error(`Agentic has no upstream: ${name}`);
+    }
+    const dirty = await dirtyPaths(libraryDir, entry.path);
+    if (dirty.length > 0 && !force) {
+        throw new Error(`Package has dirty local changes: ${name}\n` +
+            dirty.map((path) => `  ${path}`).join("\n") +
+            "\nRun jawfish update --force " +
+            name +
+            " to replace them.");
+    }
+    const acquired = await acquireSource(entry.upstream);
+    const destination = resolveInside(libraryDir, entry.path);
+    await rm(destination, { force: true, recursive: true });
+    await mkdir(dirname(destination), { recursive: true });
+    await cp(acquired.packagePath, destination, { recursive: true });
+}
+async function updateAllPackages(libraryDir, catalog, force) {
+    const summary = { failed: [], skipped: [], updated: [] };
+    for (const name of Object.keys(catalog.jawfish)) {
+        const entry = catalog.jawfish[name];
+        if (entry.upstream === undefined) {
+            summary.skipped.push(name);
+            continue;
+        }
+        try {
+            await updatePackage(libraryDir, catalog, name, force);
+            summary.updated.push(name);
+        }
+        catch (error) {
+            const failure = bulkUpdateFailure(name, error);
+            summary.failed.push(failure);
+            console.error(`Failed to update ${name}:\n${failure.details}`);
+        }
+    }
+    return summary;
+}
+function printBulkUpdateSummary(summary) {
+    console.log(`Updated: ${formatSummaryNames(summary.updated)}`);
+    console.log(`Skipped: ${formatSummaryNames(summary.skipped)}`);
+    console.log(`Failed: ${formatBulkUpdateFailures(summary.failed)}`);
+}
+function formatSummaryNames(names) {
+    return names.length === 0 ? "none" : names.join(", ");
+}
+function formatBulkUpdateFailures(failures) {
+    if (failures.length === 0) {
+        return "none";
+    }
+    return failures
+        .map((failure) => `${failure.name} (${failure.message})`)
+        .join(", ");
+}
+function bulkUpdateFailure(name, error) {
+    const details = stringifyError(error);
+    return {
+        details,
+        message: details.split("\n")[0],
+        name,
+    };
+}
+function stringifyError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function reinstallInScopeIfPresent(libraryDir, catalog, name, scope, config) {
+    const manifest = await readManifest(scope);
+    const entry = manifest.jawfish[name];
+    if (entry !== undefined) {
+        assertConfiguredTool(config, entry.tool);
+        await materialize(libraryDir, catalog, name, scope, entry.tool);
+    }
+}
+async function resolveTool(config) {
+    const allowedTools = config.allowedTools.length > 0 ? config.allowedTools : [...defaultTools];
+    config.allowedTools = allowedTools;
+    if (config.defaultTool !== undefined) {
+        assertConfiguredTool(config, config.defaultTool);
+        return config.defaultTool;
+    }
+    const selected = await promptForTool(allowedTools);
+    if (selected === "") {
+        throw new Error("No default tool selected");
+    }
+    assertConfiguredTool(config, selected);
+    config.defaultTool = selected;
+    await writeConfig(config);
+    return selected;
+}
+function assertConfiguredTool(config, tool) {
+    if (!config.allowedTools.includes(tool)) {
+        throw new Error(`Tool is not configured: ${tool}. Configured tools: ${config.allowedTools.join(", ")}`);
+    }
+    assertSupportedTool(tool);
+}
+async function loadConfig() {
+    const path = await existingConfigPath();
+    const parsed = path === undefined
+        ? {}
+        : JSON.parse(await readFile(path, "utf8"));
+    const config = {
+        allowedTools: parsed.allowedTools ?? [...defaultTools],
+        contentLibrary: parsed.contentLibrary ?? process.env.JAWFISH_CONTENT_LIBRARY,
+        defaultTool: parsed.defaultTool,
+    };
+    let changed = path === undefined ||
+        parsed.allowedTools === undefined ||
+        (parsed.contentLibrary === undefined &&
+            process.env.JAWFISH_CONTENT_LIBRARY !== undefined);
+    const envDefaultTool = process.env.JAWFISH_DEFAULT_TOOL;
+    if (config.defaultTool === undefined && envDefaultTool !== undefined) {
+        assertConfiguredTool(config, envDefaultTool);
+        config.defaultTool = envDefaultTool;
+        changed = true;
+    }
+    if (changed) {
+        await writeConfig(config);
+    }
+    return config;
+}
+async function writeConfig(config) {
+    await writeJson(configPath(), config);
+}
+async function resolveContentLibrary(config) {
+    if (config.contentLibrary === undefined || config.contentLibrary === "") {
+        throw new Error(`Missing contentLibrary in ${configPath()}\n` +
+            "Set it to your jawfish content library path or clone URL.");
+    }
+    const configured = isAbsolute(config.contentLibrary)
+        ? config.contentLibrary
+        : resolve(process.cwd(), config.contentLibrary);
+    if (resolve(configured) === resolve(deprecatedLibraryPath())) {
+        throw new Error(`Nested content library is no longer supported: ${configured}\n` +
+            `Move the library to ${managedLibraryPath()} and update ${configPath()}.`);
+    }
+    if ((await exists(configured)) && !(await isBareRepository(configured))) {
+        await ensureLibraryIgnore(configured);
+        return configured;
+    }
+    const libraryDir = managedLibraryPath();
+    if (await exists(join(libraryDir, ".git"))) {
+        await ensureLibraryIgnore(libraryDir);
+        return libraryDir;
+    }
+    await mkdir(jawfishHome(), { recursive: true });
+    await initializeManagedLibrary(config.contentLibrary, libraryDir);
+    await ensureLibraryIgnore(libraryDir);
+    return libraryDir;
+}
+async function initializeManagedLibrary(source, libraryDir) {
+    await runCommand("git", ["init"], libraryDir);
+    await runCommand("git", ["remote", "add", "origin", source], libraryDir);
+    await runCommand("git", ["fetch", "origin"], libraryDir);
+    const branch = await remoteDefaultBranch(libraryDir);
+    await runCommand("git", ["checkout", "-B", branch, `origin/${branch}`], libraryDir);
+    await runCommand("git", ["branch", "--set-upstream-to", `origin/${branch}`, branch], libraryDir);
+}
+async function remoteDefaultBranch(libraryDir) {
+    const result = await runCommand("git", ["ls-remote", "--symref", "origin", "HEAD"], libraryDir);
+    const match = /^ref: refs\/heads\/([^\t]+)\tHEAD$/mu.exec(result.stdout);
+    if (match === null) {
+        throw new Error("Could not determine content library default branch");
+    }
+    return match[1];
+}
+async function readCatalog(libraryDir) {
+    const indexPath = join(libraryDir, indexCatalogFile);
+    if (await exists(indexPath)) {
+        const parsed = JSON.parse(await readFile(indexPath, "utf8"));
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            throw new Error(`Invalid catalog at ${indexPath}: expected name-keyed object`);
+        }
+        return validateCatalog(indexPath, {
+            jawfish: parsed,
+        });
+    }
+    const legacyPath = join(libraryDir, catalogFile);
+    if (await exists(legacyPath)) {
+        const parsed = JSON.parse(await readFile(legacyPath, "utf8"));
+        return validateCatalog(legacyPath, { jawfish: parsed.jawfish ?? {} });
+    }
+    return { jawfish: {} };
+}
+async function writeCatalog(libraryDir, catalog) {
+    await writeJson(join(libraryDir, indexCatalogFile), catalog.jawfish);
+    await rm(join(libraryDir, catalogFile), { force: true });
+}
+function validateCatalog(path, catalog) {
+    const issues = [];
+    for (const [name, entry] of Object.entries(catalog.jawfish)) {
+        issues.push(...catalogEntryIssues(name, entry));
+    }
+    if (issues.length > 0) {
+        throw new Error(`Invalid catalog at ${path}: ${issues.join("; ")}`);
+    }
+    return catalog;
+}
+function catalogEntryIssues(name, entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        return [`${name}: expected object`];
+    }
+    const issues = [];
+    if (!("description" in entry) || typeof entry.description !== "string") {
+        issues.push(`${name}.description`);
+    }
+    if (!("path" in entry) || typeof entry.path !== "string") {
+        issues.push(`${name}.path`);
+    }
+    if (!("type" in entry) ||
+        (entry.type !== "skill" &&
+            entry.type !== "agent" &&
+            entry.type !== "prompt")) {
+        issues.push(`${name}.type`);
+    }
+    if ("upstream" in entry && typeof entry.upstream !== "string") {
+        issues.push(`${name}.upstream`);
+    }
+    return issues;
+}
+function printCatalogEntry(name, entry, tool) {
+    if (entry === undefined) {
+        return;
+    }
+    console.log(`${name} (${entry.type})`);
+    console.log(entry.description);
+    console.log(`tool: ${tool}`);
+    console.log(`path: ${entry.path}`);
+    if (entry.upstream !== undefined) {
+        console.log(`upstream: ${entry.upstream}`);
+    }
+}
+async function readManifest(scope) {
+    const path = manifestPath(scope);
+    if (!(await exists(path))) {
+        return { jawfish: {} };
+    }
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return { jawfish: parsed.jawfish ?? {} };
+}
+async function writeManifest(scope, manifest) {
+    await writeJson(manifestPath(scope), manifest);
+}
+async function inferType(packagePath, entryFile) {
+    const skillPath = join(packagePath, "SKILL.md");
+    const agentPath = join(packagePath, "AGENT.md");
+    const detectedTypes = [];
+    if (await exists(skillPath)) {
+        detectedTypes.push("skill");
+    }
+    if (await exists(agentPath)) {
+        detectedTypes.push("agent");
+    }
+    if (detectedTypes.length === 0 &&
+        (await hasPromptSignal(packagePath, entryFile))) {
+        detectedTypes.push("prompt");
+    }
+    if (detectedTypes.length === 1) {
+        return detectedTypes[0];
+    }
+    const envImportType = process.env.JAWFISH_IMPORT_TYPE;
+    if (envImportType !== undefined) {
+        if (isAgenticType(envImportType)) {
+            return envImportType;
+        }
+        throw new Error(`Invalid JAWFISH_IMPORT_TYPE: ${envImportType}`);
+    }
+    return promptForAgenticType(packagePath);
+}
+async function hasPromptSignal(packagePath, entryFile) {
+    if (entryFile !== undefined && promptExtensions.has(extname(entryFile))) {
+        return true;
+    }
+    const entries = await readdir(packagePath, { withFileTypes: true });
+    const promptFiles = entries.filter((entry) => {
+        return entry.isFile() && promptExtensions.has(extname(entry.name));
+    });
+    return promptFiles.length === 1;
+}
+function inferPackageName(packagePath) {
+    return basename(packagePath).replace(/\.[^.]+$/, "");
+}
+function configPath() {
+    return join(jawfishHome(), "config.json");
+}
+function legacyConfigPath() {
+    return join(xdgConfigHome(), "jawfish", "config.json");
+}
+async function existingConfigPath() {
+    if (await exists(configPath())) {
+        return configPath();
+    }
+    if (await exists(legacyConfigPath())) {
+        return legacyConfigPath();
+    }
+    return undefined;
+}
+function managedLibraryPath() {
+    return jawfishHome();
+}
+function deprecatedLibraryPath() {
+    return join(jawfishHome(), "library");
+}
+function manifestPath(scope) {
+    if (scope === "project") {
+        return join(process.cwd(), projectManifestFile);
+    }
+    return join(jawfishHome(), projectManifestFile);
+}
+function codexHome() {
+    return process.env.CODEX_HOME ?? join(homeDir(), ".codex");
+}
+function toolPaths() {
+    return {
+        codexHome: codexHome(),
+        homeDir: homeDir(),
+        projectDir: process.cwd(),
+    };
+}
+function getScope(args) {
+    return args.global ? "global" : "project";
+}
+function homeDir() {
+    return process.env.HOME ?? homedir();
+}
+function jawfishHome() {
+    return process.env.JAWFISH_HOME ?? join(homeDir(), ".jawfish");
+}
+function xdgConfigHome() {
+    return process.env.XDG_CONFIG_HOME ?? join(homeDir(), ".config");
+}
+async function isBareRepository(path) {
+    const result = await runCommand("git", ["rev-parse", "--is-bare-repository"], path, false);
+    return result.exitCode === 0 && result.stdout.trim() === "true";
+}
+function parseArgs(args) {
+    const parsed = {
+        force: false,
+        global: false,
+        help: false,
+        positionals: [],
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case "-F":
+            case "--force":
+                parsed.force = true;
+                break;
+            case "-g":
+            case "--global":
+                parsed.global = true;
+                break;
+            case "-h":
+            case "--help":
+                parsed.help = true;
+                break;
+            case "--name": {
+                const name = args[index + 1];
+                if (name === undefined) {
+                    throw new Error("--name requires a value");
+                }
+                parsed.name = name;
+                index += 1;
+                break;
+            }
+            default:
+                parsed.positionals.push(arg);
+                break;
+        }
+    }
+    return parsed;
+}
+function printRootHelp() {
+    console.log(`jawfish ${version}
+
+Usage: jawfish <command> [options]
+
+Commands:
+${commandNames
+        .map((command) => `  ${command.padEnd(10)}${commandSpecs[command].summary}`)
+        .join("\n")}
+
+Options:
+  -h, --help      Show help
+  -v, --version   Show version`);
+}
+function printCommandHelp(command) {
+    const spec = commandSpecs[command];
+    console.log(`${spec.description}
+
+Usage: ${spec.usage}
+
+Options:
+${spec.options.map((option) => `  ${option}`).join("\n")}`);
+}
+async function syncLibrary(libraryDir) {
+    if (!(await exists(join(libraryDir, ".git")))) {
+        return;
+    }
+    const upstream = await runCommand("git", ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], libraryDir, false);
+    if (upstream.exitCode !== 0) {
+        return;
+    }
+    await runCommand("git", ["pull", "--ff-only"], libraryDir);
+}
+async function dirtyPaths(libraryDir, packagePath) {
+    if (!(await exists(join(libraryDir, ".git")))) {
+        return [];
+    }
+    const result = await runCommand("git", ["status", "--porcelain", "--", packagePath], libraryDir);
+    return result.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+async function commitAndPush(libraryDir, message) {
+    if (!(await exists(join(libraryDir, ".git")))) {
+        return { ok: true };
+    }
+    await ensureLibraryIgnore(libraryDir);
+    await runCommand("git", ["add", "."], libraryDir);
+    const status = await runCommand("git", ["status", "--porcelain"], libraryDir);
+    if (status.stdout.trim() === "") {
+        return { ok: true };
+    }
+    await runCommand("git", ["commit", "-m", message], libraryDir);
+    const push = await runCommand("git", ["push"], libraryDir, false);
+    if (push.exitCode !== 0) {
+        return { ok: false, error: push.stderr || push.stdout };
+    }
+    return { ok: true };
+}
+async function pushLibraryChanges(libraryDir, message) {
+    const pushResult = await commitAndPush(libraryDir, message);
+    if (pushResult.ok) {
+        return true;
+    }
+    printPushFailure(pushResult.error, libraryDir);
+    return false;
+}
+function printPushFailure(error, libraryDir) {
+    console.error("Library commit was created, but push failed.");
+    console.error(error.trim());
+    console.error(`Recover with: git -C ${libraryDir} push`);
+}
+async function runCommand(command, args, cwd, throwOnFailure = true) {
+    const child = spawn(command, args, {
+        cwd,
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        readStream(child.stdout),
+        readStream(child.stderr),
+        waitForExit(child),
+    ]);
+    const result = { exitCode, stderr, stdout };
+    if (throwOnFailure && exitCode !== 0) {
+        throw new Error(`${command} ${args.join(" ")} failed (${exitCode ?? "unknown"})\n${stderr}`);
+    }
+    return result;
+}
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+async function ensureLibraryIgnore(libraryDir) {
+    const ignorePath = join(libraryDir, ".gitignore");
+    const existing = (await exists(ignorePath))
+        ? await readFile(ignorePath, "utf8")
+        : "";
+    const existingEntries = new Set(existing.split("\n").map((line) => line.trim()));
+    const missing = libraryIgnoreEntries.filter((entry) => !existingEntries.has(entry));
+    if (missing.length === 0) {
+        return;
+    }
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await writeFile(ignorePath, `${existing}${separator}${missing.join("\n")}\n`);
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+function resolveInside(root, path) {
+    const resolved = resolve(root, path);
+    const parentRelative = relative(root, resolved);
+    if (parentRelative.startsWith("..") || isAbsolute(parentRelative)) {
+        throw new Error(`Path escapes content library: ${path}`);
+    }
+    return resolved;
+}
+function isUrl(value) {
+    return /^https?:\/\//u.test(value);
+}
+const promptExtensions = new Set([".md", ".txt", ".prompt"]);
+function isHelp(value) {
+    return value === "--help" || value === "-h";
+}
+function isCommandName(value) {
+    return Object.hasOwn(commandSpecs, value);
+}
+function catalogHasAgentic(catalog, name) {
+    return Object.hasOwn(catalog.jawfish, name);
+}
+async function isMainModule() {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const modulePath = await realpath(fileURLToPath(import.meta.url));
+    const argvPath = await realpath(process.argv[1]);
+    return modulePath === argvPath;
+}
+async function waitForExit(child) {
+    return new Promise((resolve, reject) => {
+        child.on("close", resolve);
+        child.on("error", reject);
+    });
+}
+async function readStream(stream) {
+    let output = "";
+    for await (const chunk of stream) {
+        output += String(chunk);
+    }
+    return output;
+}
+if (await isMainModule()) {
+    process.exitCode = await run(process.argv.slice(2));
+}

package/dist/tool-adapters.js

@@ -0,0 +1,41 @@
+import { join } from "node:path";
+export const supportedTools = ["codex", "claude-code", "hermes"];
+const adapters = {
+    codex: {
+        destinationPath: (name, type, scope, paths) => join(codexRoot(scope, paths), typeFolder(type), name),
+    },
+    "claude-code": {
+        destinationPath: (name, type, scope, paths) => join(scopeRoot(scope, paths), ".claude", typeFolder(type), name),
+    },
+    hermes: {
+        destinationPath: (name, type, scope, paths) => join(scopeRoot(scope, paths), ".hermes", typeFolder(type), name),
+    },
+};
+export function assertSupportedTool(tool) {
+    if (!isSupportedTool(tool)) {
+        throw new Error(`Unsupported tool: ${tool}. Supported tools: ${supportedTools.join(", ")}`);
+    }
+}
+function isSupportedTool(tool) {
+    return Object.hasOwn(adapters, tool);
+}
+export function destinationPath(name, type, scope, tool, paths) {
+    assertSupportedTool(tool);
+    return adapters[tool].destinationPath(name, type, scope, paths);
+}
+export function typeFolder(type) {
+    switch (type) {
+        case "agent":
+            return "agents";
+        case "prompt":
+            return "prompts";
+        case "skill":
+            return "skills";
+    }
+}
+function scopeRoot(scope, paths) {
+    return scope === "project" ? paths.projectDir : paths.homeDir;
+}
+function codexRoot(scope, paths) {
+    return scope === "project" ? join(paths.projectDir, ".codex") : paths.codexHome;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@devdogfish/jawfish",
+  "version": "0.1.0",
+  "description": "Minimal CLI for syncing and scoping AI agent skills, agents, and prompts across tools, devices, and projects.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devdogfish/jawfish.git"
+  },
+  "files": [
+    "dist",
+    "jawfish-logo-dark.png",
+    "jawfish-logo-light.png"
+  ],
+  "bin": {
+    "jawfish": "dist/main.js"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "jawfish": "node --experimental-strip-types src/main.ts",
+    "prepack": "bun run build",
+    "sandcastle": "npx tsx .sandcastle/main.mts",
+    "test": "node --test --experimental-strip-types test/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-hero/sandcastle": "^0.10.0",
+    "@clack/prompts": "^1.6.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "@types/node": "^26.0.0",
+    "typescript": "^6.0.3"
+  }
+}