@slashfi/agents-sdk 0.50.5 → 0.60.0

package/src/init.test.ts

@@ -0,0 +1,419 @@
+/**
+ * Tests for init + materialize modules.
+ *
+ * Focuses on:
+ * - parseTarget parsing (preset-based)
+ * - Skill template generation
+ * - Type generation from tool schemas
+ * - Materialization file structure
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { parseTarget, runInit, loadPresets, getPreset, renderContent } from "./init.js";
+import type { SkillTarget, Preset } from "./init.js";
+import { materializeRef } from "./materialize.js";
+import type { Adk } from "./config-store.js";
+import { createAdk } from "./config-store.js";
+import type { FsStore } from "./agent-definitions/config.js";
+
+// ============================================
+// Helpers
+// ============================================
+
+const TEST_DIR = join(import.meta.dir, "../.test-output");
+
+function createMemoryStore(): FsStore & { files: Map<string, string> } {
+  const files = new Map<string, string>();
+  return {
+    files,
+    async readFile(path: string) {
+      return files.get(path) ?? null;
+    },
+    async writeFile(path: string, content: string) {
+      files.set(path, content);
+    },
+  };
+}
+
+function cleanup() {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true });
+  }
+}
+
+// ============================================
+// Presets
+// ============================================
+
+describe("presets", () => {
+  test("loads all preset files", () => {
+    const presets = loadPresets();
+    expect(presets.size).toBeGreaterThanOrEqual(4);
+    expect(presets.has("claude")).toBe(true);
+    expect(presets.has("cursor")).toBe(true);
+    expect(presets.has("copilot")).toBe(true);
+    expect(presets.has("windsurf")).toBe(true);
+  });
+
+  test("claude preset writes SKILL.md", () => {
+    const preset = getPreset("claude");
+    expect(preset).toBeDefined();
+    expect(preset!.filename).toContain("SKILL.md");
+  });
+
+  test("cursor preset targets .agents/skills", () => {
+    const preset = getPreset("cursor");
+    expect(preset).toBeDefined();
+    expect(preset!.defaultPath).toBe(".agents/skills");
+  });
+
+  test("copilot preset targets .github/skills", () => {
+    const preset = getPreset("copilot");
+    expect(preset).toBeDefined();
+    expect(preset!.defaultPath).toBe(".github/skills");
+  });
+});
+
+// ============================================
+// parseTarget
+// ============================================
+
+describe("parseTarget", () => {
+  test("parses preset name with default path", () => {
+    const result = parseTarget("claude");
+    expect(result.preset.name).toBe("claude");
+    expect(result.path).toContain(".claude/skills");
+  });
+
+  test("parses preset:path override", () => {
+    const result = parseTarget("cursor:/tmp/my-rules");
+    expect(result.preset.name).toBe("cursor");
+    expect(result.path).toBe("/tmp/my-rules");
+  });
+
+  test("parses all preset names", () => {
+    for (const name of ["claude", "cursor", "copilot", "windsurf"]) {
+      const result = parseTarget(name);
+      expect(result.preset.name).toBe(name);
+    }
+  });
+
+  test("parses preset with custom path", () => {
+    const result = parseTarget("claude:/tmp/custom");
+    expect(result.preset.name).toBe("claude");
+    expect(result.path).toBe("/tmp/custom");
+  });
+
+  test("throws on unknown target", () => {
+    expect(() => parseTarget("unknown")).toThrow("Unknown preset");
+  });
+
+  test("throws on unknown with path", () => {
+    expect(() => parseTarget("vscode:/tmp")).toThrow("Unknown target");
+  });
+});
+
+// ============================================
+// renderContent
+// ============================================
+
+describe("renderContent", () => {
+  const body = "Test content";
+  const meta = { name: "test", description: "Test desc" };
+
+  test("includes YAML frontmatter with name and description", () => {
+    const result = renderContent(body, meta);
+    expect(result).toContain("---");
+    expect(result).toContain("name: test");
+    expect(result).toContain("description: Test desc");
+    expect(result).toContain("Test content");
+  });
+});
+
+// ============================================
+// runInit
+// ============================================
+
+describe("runInit", () => {
+  beforeEach(cleanup);
+  afterEach(cleanup);
+
+  test("writes claude skill file to target path", async () => {
+    const store = createMemoryStore();
+    const adk = createAdk(store);
+    const skillDir = join(TEST_DIR, "claude-skills");
+    const preset = getPreset("claude")!;
+
+    await runInit(adk, [{ preset, path: skillDir }]);
+
+    const skillPath = join(skillDir, preset.filename);
+    expect(existsSync(skillPath)).toBe(true);
+
+    const content = readFileSync(skillPath, "utf-8");
+    expect(content).toContain("name: adk");
+    expect(content).toContain("description:");
+    expect(content).toContain("adk ref call");
+  });
+
+  test("writes cursor skill file to target path", async () => {
+    const store = createMemoryStore();
+    const adk = createAdk(store);
+    const skillDir = join(TEST_DIR, "cursor-skills");
+    const preset = getPreset("cursor")!;
+
+    await runInit(adk, [{ preset, path: skillDir }]);
+
+    const skillPath = join(skillDir, preset.filename);
+    expect(existsSync(skillPath)).toBe(true);
+
+    const content = readFileSync(skillPath, "utf-8");
+    expect(content).toContain("name: adk");
+    expect(content).toContain("adk ref call");
+  });
+
+  test("saves targets to config", async () => {
+    const store = createMemoryStore();
+    const adk = createAdk(store);
+    const skillDir = join(TEST_DIR, "save-test");
+    const preset = getPreset("claude")!;
+
+    await runInit(adk, [{ preset, path: skillDir }]);
+
+    const configRaw = store.files.get("consumer-config.json");
+    expect(configRaw).toBeDefined();
+    const config = JSON.parse(configRaw!);
+    expect(config.targets).toBeDefined();
+  });
+
+  test("adds default registry on first run", async () => {
+    const store = createMemoryStore();
+    const adk = createAdk(store);
+
+    await runInit(adk, []);
+
+    const configRaw = store.files.get("consumer-config.json");
+    expect(configRaw).toBeDefined();
+    const config = JSON.parse(configRaw!);
+    expect(config.registries).toBeDefined();
+    expect(config.registries.some((r: any) => r.url === "https://registry.slash.com")).toBe(true);
+  });
+
+  test("is idempotent with default registry", async () => {
+    const store = createMemoryStore();
+    const adk = createAdk(store);
+
+    await runInit(adk, []);
+    await runInit(adk, []);
+
+    const config = JSON.parse(store.files.get("consumer-config.json")!);
+    const slashRegistries = config.registries.filter((r: any) => r.url === "https://registry.slash.com");
+    expect(slashRegistries.length).toBe(1);
+  });
+});
+
+// ============================================
+// Type Generation (via materializeRef)
+// ============================================
+
+describe("type generation", () => {
+  beforeEach(cleanup);
+  afterEach(cleanup);
+
+  test("generates valid .d.ts from tool schemas", async () => {
+    const configDir = join(TEST_DIR, "types-test");
+
+    const mockTools = [
+      {
+        name: "search_pages",
+        description: "Search for Notion pages",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string" },
+            limit: { type: "number" },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "create_page",
+        description: "Create a new page in a database",
+        inputSchema: {
+          type: "object",
+          properties: {
+            parent_id: { type: "string" },
+            title: { type: "string" },
+          },
+          required: ["parent_id", "title"],
+        },
+      },
+      {
+        name: "API-get-block",
+        description: "Get a block by ID",
+        inputSchema: {
+          type: "object",
+          properties: {
+            block_id: { type: "string" },
+          },
+          required: ["block_id"],
+        },
+      },
+    ];
+
+    const adk = {
+      ref: {
+        inspect: async () => ({
+          path: "notion",
+          description: "Notion MCP agent",
+          tools: mockTools,
+        }),
+        resources: async () => ({ result: { resources: [] } }),
+      },
+      readConfig: async () => ({}),
+      writeConfig: async () => {},
+    } as unknown as Adk;
+
+    const result = await materializeRef(adk, "notion", configDir);
+
+    expect(result.toolCount).toBe(3);
+    expect(result.typesGenerated).toBe(true);
+
+    // Check .d.ts file
+    const dtsPath = join(configDir, "refs", "notion", "types", "notion.d.ts");
+    expect(existsSync(dtsPath)).toBe(true);
+
+    const dts = readFileSync(dtsPath, "utf-8");
+    expect(dts).toContain("export interface NotionTools");
+    expect(dts).toContain('"search_pages"');
+    expect(dts).toContain('"create_page"');
+    expect(dts).toContain('"API-get-block"');
+    expect(dts).toContain("Search for Notion pages");
+    expect(dts).toContain("Create a new page in a database");
+    expect(dts).toContain("export declare const tools");
+  });
+
+  test("generates tool.json files per tool", async () => {
+    const configDir = join(TEST_DIR, "tool-json-test");
+
+    const mockTools = [
+      {
+        name: "search",
+        description: "Search",
+        inputSchema: { type: "object", properties: { q: { type: "string" } } },
+      },
+    ];
+
+    const adk = {
+      ref: {
+        inspect: async () => ({ tools: mockTools }),
+        resources: async () => ({ result: { resources: [] } }),
+      },
+    } as unknown as Adk;
+
+    const result = await materializeRef(adk, "test-agent", configDir);
+
+    expect(result.toolCount).toBe(1);
+
+    const toolPath = join(configDir, "refs", "test-agent", "tools", "search.tool.json");
+    expect(existsSync(toolPath)).toBe(true);
+
+    const tool = JSON.parse(readFileSync(toolPath, "utf-8"));
+    expect(tool.name).toBe("search");
+    expect(tool.description).toBe("Search");
+    expect(tool.inputSchema.properties.q.type).toBe("string");
+  });
+
+  test("generates agent.json metadata", async () => {
+    const configDir = join(TEST_DIR, "agent-json-test");
+
+    const adk = {
+      ref: {
+        inspect: async () => ({
+          description: "Test agent",
+          tools: [{ name: "tool1", description: "A tool" }],
+        }),
+        resources: async () => ({ result: { resources: [] } }),
+      },
+    } as unknown as Adk;
+
+    await materializeRef(adk, "myagent", configDir);
+
+    const metaPath = join(configDir, "refs", "myagent", "agent.json");
+    expect(existsSync(metaPath)).toBe(true);
+
+    const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+    expect(meta.name).toBe("myagent");
+    expect(meta.description).toBe("Test agent");
+    expect(meta.toolCount).toBe(1);
+    expect(meta.tools).toEqual(["tool1"]);
+    expect(meta.materializedAt).toBeDefined();
+  });
+
+  test("handles special characters in tool names", async () => {
+    const configDir = join(TEST_DIR, "special-chars-test");
+
+    const adk = {
+      ref: {
+        inspect: async () => ({
+          tools: [
+            { name: "API-post-search/v2", description: "Search v2" },
+            { name: "get:users.list", description: "List users" },
+          ],
+        }),
+        resources: async () => ({ result: { resources: [] } }),
+      },
+    } as unknown as Adk;
+
+    const result = await materializeRef(adk, "test", configDir);
+    expect(result.toolCount).toBe(2);
+
+    // Check filenames are sanitized
+    const toolsDir = join(configDir, "refs", "test", "tools");
+    expect(existsSync(join(toolsDir, "API-post-search_v2.tool.json"))).toBe(true);
+    expect(existsSync(join(toolsDir, "get_users_list.tool.json"))).toBe(true);
+
+    // Check .d.ts handles them
+    const dts = readFileSync(join(configDir, "refs", "test", "types", "test.d.ts"), "utf-8");
+    expect(dts).toContain('"API-post-search/v2"');
+    expect(dts).toContain('"get:users.list"');
+  });
+
+  test("handles inspect failure gracefully", async () => {
+    const configDir = join(TEST_DIR, "fail-test");
+
+    const adk = {
+      ref: {
+        inspect: async () => { throw new Error("Not authenticated"); },
+        resources: async () => { throw new Error("Not authenticated"); },
+      },
+    } as unknown as Adk;
+
+    const result = await materializeRef(adk, "failing", configDir);
+    expect(result.toolCount).toBe(0);
+    expect(result.skillCount).toBe(0);
+    expect(result.typesGenerated).toBe(false);
+  });
+
+  test("pascalCase conversion works for type name", async () => {
+    const configDir = join(TEST_DIR, "pascal-test");
+
+    const adk = {
+      ref: {
+        inspect: async () => ({
+          tools: [{ name: "test", description: "Test" }],
+        }),
+        resources: async () => ({ result: { resources: [] } }),
+      },
+    } as unknown as Adk;
+
+    await materializeRef(adk, "my-cool-agent", configDir);
+
+    const dts = readFileSync(
+      join(configDir, "refs", "my-cool-agent", "types", "my-cool-agent.d.ts"),
+      "utf-8",
+    );
+    expect(dts).toContain("export interface MyCoolAgentTools");
+  });
+});

package/src/init.ts

@@ -0,0 +1,211 @@
+/**
+ * ADK Init — Setup + skill injection for coding agents.
+ *
+ * Uses a preset-based system for scalability:
+ * - Presets are JSON files in src/presets/ (one per coding agent)
+ * - All use the agentskills.io SKILL.md standard
+ * - Adding a new coding agent = adding one JSON file
+ *
+ * Non-interactive by design. The coding agent is the UX layer.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import type { Adk } from "./config-store.js";
+
+// ============================================
+// Types
+// ============================================
+
+export interface Preset {
+  name: string;
+  defaultPath: string;
+  filename: string;
+}
+
+export interface SkillTarget {
+  preset: Preset;
+  path: string;
+}
+
+// ============================================
+// Preset Loading
+// ============================================
+
+// Presets are inlined to avoid import.meta/CJS compatibility issues.
+// To add a new coding agent, add an entry here and a JSON file in src/presets/.
+const BUILTIN_PRESETS: Preset[] = [
+  { name: "claude", defaultPath: "~/.claude/skills", filename: "adk/SKILL.md" },
+  { name: "cursor", defaultPath: ".agents/skills", filename: "adk/SKILL.md" },
+  { name: "codex", defaultPath: ".agents/skills", filename: "adk/SKILL.md" },
+  { name: "copilot", defaultPath: ".github/skills", filename: "adk/SKILL.md" },
+  { name: "windsurf", defaultPath: ".windsurf/skills", filename: "adk/SKILL.md" },
+  { name: "hermes", defaultPath: "~/.hermes/skills", filename: "adk/SKILL.md" },
+];
+
+let _presets: Map<string, Preset> | null = null;
+
+export function loadPresets(): Map<string, Preset> {
+  if (_presets) return _presets;
+  _presets = new Map();
+  for (const preset of BUILTIN_PRESETS) {
+    _presets.set(preset.name, preset);
+  }
+  return _presets;
+}
+
+export function getPreset(name: string): Preset | undefined {
+  return loadPresets().get(name);
+}
+
+export function listPresets(): Preset[] {
+  return Array.from(loadPresets().values());
+}
+
+// ============================================
+// Skill Content Templates
+// ============================================
+
+const ADK_SKILL_CONTENT = `adk is the Agent Development Kit CLI.
+
+Config location: run \`adk config-path\` to find the config directory.
+Installed refs: run \`adk ref list\` to see configured agents.
+
+Each installed ref has local docs at the config path under refs/<name>/:
+  - tools/*.tool.json — full tool schemas (inputSchema, description)
+  - skills/ — usage guides and patterns from the agent
+  - types/*.d.ts — TypeScript type definitions
+
+## Commands
+
+To call a tool: \`adk ref call <name> <tool> '{"param": "value"}'\`
+To browse available agents: \`adk registry browse slash\`
+To install an agent: \`adk ref add <name>\`
+To authenticate: \`adk ref auth <name>\`
+To check auth status: \`adk ref auth-status <name>\`
+To inspect an agent: \`adk ref inspect <name>\`
+To view tool schemas: \`adk ref inspect <name> --full\`
+To list resources: \`adk ref resources <name>\`
+To read a resource: \`adk ref read <name> <uri>\`
+`;
+
+export function renderContent(
+  content: string,
+  meta: { name: string; description: string },
+): string {
+  return `---
+name: ${meta.name}
+description: ${meta.description}
+---
+${content}`;
+}
+
+// ============================================
+// Target Parsing
+// ============================================
+
+function expandHome(p: string): string {
+  if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+export function parseTarget(value: string): SkillTarget {
+  const colonIdx = value.indexOf(":");
+
+  if (colonIdx === -1) {
+    // Just a preset name
+    const preset = getPreset(value);
+    if (!preset) {
+      const presetNames = Array.from(loadPresets().keys()).join(", ");
+      throw new Error(`Unknown preset: ${value}. Available: ${presetNames}`);
+    }
+    return { preset, path: expandHome(preset.defaultPath) };
+  }
+
+  const key = value.slice(0, colonIdx);
+  const path = value.slice(colonIdx + 1);
+
+  // Check if key is a preset name (with custom path)
+  const preset = getPreset(key);
+  if (preset) {
+    return { preset, path: expandHome(path || preset.defaultPath) };
+  }
+
+  const presetNames = Array.from(loadPresets().keys()).join(", ");
+  throw new Error(`Unknown target: ${key}. Available presets: ${presetNames}`);
+}
+
+// ============================================
+// Skill Installation
+// ============================================
+
+function ensureWrite(path: string, content: string): void {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, content, "utf-8");
+}
+
+export function installSkill(target: SkillTarget): string {
+  const outputPath = join(resolve(target.path), target.preset.filename);
+  const content = renderContent(ADK_SKILL_CONTENT, {
+    name: "adk",
+    description: "When connecting to APIs, calling remote tools, managing integrations, or the user asks about adk",
+  });
+  ensureWrite(outputPath, content);
+  return outputPath;
+}
+
+
+// ============================================
+// Init Command
+// ============================================
+
+const DEFAULT_REGISTRY_URL = "https://registry.slash.com";
+const DEFAULT_REGISTRY_NAME = "public";
+
+export async function runInit(adk: Adk, targets: SkillTarget[]): Promise<void> {
+  // 1. Ensure default registry
+  const registries = await adk.registry.list();
+  const hasDefault = registries.some(
+    (r) => r.url === DEFAULT_REGISTRY_URL || r.name === DEFAULT_REGISTRY_NAME,
+  );
+  if (!hasDefault) {
+    await adk.registry.add({ url: DEFAULT_REGISTRY_URL, name: DEFAULT_REGISTRY_NAME });
+    console.log(`\x1b[32m\u2713\x1b[0m Set default registry: ${DEFAULT_REGISTRY_URL}`);
+  } else {
+    console.log(`\x1b[32m\u2713\x1b[0m Default registry already configured: ${DEFAULT_REGISTRY_URL}`);
+  }
+
+  // 2. Install skills to targets
+  if (targets.length === 0) {
+    console.log(`\nTo install skills, re-run with targets:\n`);
+    const presets = listPresets();
+    for (const preset of presets) {
+      console.log(`  adk init --target ${preset.name}`);
+    }
+    console.log(`\nCustom path: adk init --target <preset>:<path>`);
+    console.log(`\nAsk the user which coding agents they use,`);
+    console.log(`then run: adk init --target <preset> [--target <preset> ...]`);
+    return;
+  }
+
+  for (const target of targets) {
+    const outputPath = installSkill(target);
+    console.log(`\x1b[32m\u2713\x1b[0m Installed adk skill \u2192 ${outputPath}`);
+  }
+
+  // 3. Save targets to config
+  const config = await adk.readConfig();
+  const targetStrings = targets.map((t) => {
+    return t.path === expandHome(t.preset.defaultPath) ? t.preset.name : `${t.preset.name}:${t.path}`;
+  });
+  (config as any).targets = targetStrings;
+  await adk.writeConfig(config);
+  console.log(`\x1b[32m\u2713\x1b[0m Saved targets to config`);
+
+  console.log(`\nDone! Your coding agents now know how to use adk.`);
+  console.log(`Run \`adk init\` again anytime to refresh skills or add targets.`);
+}