opencode-agent-skills-md 1.0.0

package/packages/opencode-agent-skills-md/tests/e2e/startup-smoke.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import * as fs from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { before, describe, test } from "node:test";
+
+describe("plugin startup smoke", () => {
+  let projectRoot: string;
+
+  before(async () => {
+    projectRoot = await mkdtemp(path.join(tmpdir(), "opencode-agent-skills-md-e2e-"));
+    const skillDir = path.join(projectRoot, ".opencode", "skills", "smoke-skill");
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(
+      path.join(skillDir, "SKILL.md"),
+      [
+        "---",
+        "name: smoke-skill",
+        "description: minimal smoke skill",
+        "---",
+        "",
+        "# Smoke Skill",
+        "",
+        "Smoke test content.",
+      ].join("\n"),
+      "utf8"
+    );
+  });
+
+  test("imports the built plugin and completes a first message", async () => {
+    const module = await import("../../dist/plugin.mjs");
+    const SkillsPlugin = module.SkillsPlugin as (input: any) => Promise<any>;
+
+    const prompts: Array<{ text: string }> = [];
+    const plugin = await SkillsPlugin({
+      client: {
+        session: {
+          messages: async () => ({ data: [] }),
+          prompt: async ({ body }: any) => {
+            prompts.push({ text: body.parts[0].text });
+          },
+        },
+      },
+      $: Object.assign(((strings: TemplateStringsArray, ...values: unknown[]) => ({ text: async () => String(values.join(" ")) })) as any, {
+        cwd: () => undefined,
+      }),
+      directory: projectRoot,
+    });
+
+    await plugin["chat.message"](
+      {},
+      {
+        message: {
+          sessionID: "smoke-session",
+          model: { providerID: "test-provider", modelID: "test-model" },
+          agent: "smoke-agent",
+        },
+        parts: [{ type: "text", text: "hello smoke", synthetic: false }],
+      } as any
+    );
+
+    assert.equal(prompts.length, 1);
+    assert.match(prompts[0]!.text, /<available-skills>/);
+  });
+});

package/packages/opencode-agent-skills-md/tests/fixtures/skills/home/.claude/skills/claude-user-only-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: claude-user-only-skill
+description: user-level Claude skill fixture
+---
+
+# Claude User Skill
+
+User-level skill under `~/.claude/skills/`.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/home/.config/opencode/skills/shared-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: shared-skill
+description: user fixture that should be shadowed by project
+---
+
+# Shared Skill (User)
+
+User version.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/home/.config/opencode/skills/user-only-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: user-only-skill
+description: user-only skill fixture
+---
+
+# User Only Skill
+
+User-only skill.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.claude/skills/claude-project-only-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: claude-project-only-skill
+description: project-level Claude skill fixture
+---
+
+# Claude Project Skill
+
+Project-level skill under `.claude/skills/`.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.opencode/skills/go-tester/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: go-tester
+description: helper skill for testing go code
+metadata:
+  tags:
+    - go
+    - testing
+---
+
+# Go Tester
+
+Project skill tagged `go` and `testing`.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.opencode/skills/nested/team/nested-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: nested-skill
+description: nested skill fixture
+---
+
+# Nested Skill
+
+Nested project skill.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.opencode/skills/rust-tester/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: rust-tester
+description: helper skill for testing rust code
+metadata:
+  tags:
+    - rust
+---
+
+# Rust Tester
+
+Project skill tagged `rust` only.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.opencode/skills/scripted-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: scripted-skill
+description: scripted skill fixture
+---
+
+# Scripted Skill
+
+Scripted project skill.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.opencode/skills/scripted-skill/bin/echo.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+printf 'scripted:%s\n' "$*"

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.opencode/skills/scripted-skill/docs/reference.md

@@ -0,0 +1 @@
+Project documentation for scripted skill.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.opencode/skills/shared-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: shared-skill
+description: project version wins over user fixture
+---
+
+# Shared Skill
+
+Project version.

package/packages/opencode-agent-skills-md/tests/fixtures/skills/project/.opencode/skills/using-superpowers/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: using-superpowers
+description: bundled superpowers fixture
+---
+
+# Using Superpowers
+
+Fixture content for the superpowers bootstrap path.

package/packages/opencode-agent-skills-md/tests/integration/helpers/mock-opencode.ts

@@ -0,0 +1,114 @@
+import { mkdtemp, cp, rm } from "node:fs/promises";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, "..", "..", "fixtures", "skills");
+
+export interface FixtureWorkspace {
+  projectRoot: string;
+  homeRoot: string;
+  scriptedSkillPath: string;
+  cleanup: () => Promise<void>;
+}
+
+export interface PromptRecord {
+  text: string;
+  sessionID: string;
+}
+
+export interface MockOpencodeClient {
+  client: {
+    session: {
+      messages: (input: { path: { id: string } }) => Promise<{ data: unknown[] }>;
+      prompt: (input: { path: { id: string }; body: { parts: Array<{ text: string }> } }) => Promise<void>;
+    };
+  };
+  prompts: PromptRecord[];
+}
+
+export interface ShellRecorder {
+  shell: ((strings: TemplateStringsArray, ...values: unknown[]) => { text: () => Promise<string> }) & {
+    cwd: (directory: string) => ShellRecorder["shell"];
+    calls: Array<{ cwd: string; command: string }>;
+  };
+  calls: Array<{ cwd: string; command: string }>;
+}
+
+export async function createFixtureWorkspace(): Promise<FixtureWorkspace> {
+  const root = await mkdtemp(path.join(tmpdir(), "opencode-agent-skills-md-fixture-"));
+  const projectRoot = path.join(root, "project");
+  const homeRoot = path.join(root, "home");
+
+  await cp(path.join(fixtureRoot, "project"), projectRoot, { recursive: true });
+  await cp(path.join(fixtureRoot, "home"), homeRoot, { recursive: true });
+
+  const scriptedSkillPath = path.join(projectRoot, ".opencode", "skills", "scripted-skill");
+  await fs.chmod(path.join(scriptedSkillPath, "bin", "echo.sh"), 0o755);
+
+  const previousHome = process.env.HOME;
+  process.env.HOME = homeRoot;
+
+  return {
+    projectRoot,
+    homeRoot,
+    scriptedSkillPath,
+    cleanup: async () => {
+      if (previousHome === undefined) {
+        delete process.env.HOME;
+      } else {
+        process.env.HOME = previousHome;
+      }
+      await rm(root, { recursive: true, force: true });
+    },
+  };
+}
+
+export function createMockOpencodeClient(initialMessages: unknown[] = []): MockOpencodeClient {
+  const prompts: PromptRecord[] = [];
+
+  return {
+    prompts,
+    client: {
+      session: {
+        messages: async () => ({ data: initialMessages }),
+        prompt: async ({ path: sessionPath, body }) => {
+          const text = body.parts[0]?.text ?? "";
+          prompts.push({ text, sessionID: sessionPath.id });
+        },
+      },
+    },
+  };
+}
+
+export function createShellRecorder(): ShellRecorder {
+  const calls: Array<{ cwd: string; command: string }> = [];
+  let currentCwd = "";
+
+  const shell = Object.assign(
+    ((strings: TemplateStringsArray, ...values: unknown[]) => {
+      const command = strings.reduce((acc, chunk, index) => {
+        const value = values[index];
+        const rendered = Array.isArray(value) ? value.join(" ") : String(value ?? "");
+        return acc + chunk + rendered;
+      }, "");
+
+      calls.push({ cwd: currentCwd, command });
+
+      return {
+        text: async () => `cwd=${currentCwd}\n${command}`,
+      };
+    }) as ShellRecorder["shell"],
+    {
+      cwd(directory: string) {
+        currentCwd = directory;
+        return shell;
+      },
+      calls,
+    }
+  );
+
+  return { shell, calls };
+}

package/packages/opencode-agent-skills-md/tests/integration/plugin.test.ts

@@ -0,0 +1,316 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, test } from "node:test";
+import {
+  createFixtureWorkspace,
+  createMockOpencodeClient,
+  createShellRecorder,
+} from "./helpers/mock-opencode";
+
+describe("plugin integration", () => {
+  let workspace: Awaited<ReturnType<typeof createFixtureWorkspace>>;
+  const previousSuperpowersMode = process.env.OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE;
+
+  beforeEach(async () => {
+    workspace = await createFixtureWorkspace();
+    process.env.OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE = "true";
+  });
+
+  afterEach(async () => {
+    if (workspace) {
+      await workspace.cleanup();
+    }
+    if (previousSuperpowersMode === undefined) {
+      delete process.env.OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE;
+    } else {
+      process.env.OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE = previousSuperpowersMode;
+    }
+  });
+
+  test("discovers project and user skills deterministically", async () => {
+    const { discoverAllSkills } = await import("opencode-agent-skills-md-core");
+
+    const skills = await discoverAllSkills(workspace.projectRoot);
+
+    assert.equal(skills.get("shared-skill")?.label, "project");
+    assert.equal(skills.get("shared-skill")?.description, "project version wins over user fixture");
+    assert.equal(skills.get("nested-skill")?.description, "nested skill fixture");
+    assert.equal(skills.get("user-only-skill")?.label, "user");
+  });
+
+  test("loads startup context, tools, and reinjection hooks", async () => {
+    const { SkillsPlugin } = await import("../../src");
+
+    const client = createMockOpencodeClient();
+    const shell = createShellRecorder();
+    const plugin = await SkillsPlugin({ client: client.client, $: shell.shell, directory: workspace.projectRoot } as any);
+
+    await plugin["chat.message"](
+      {},
+      {
+        message: {
+          sessionID: "session-startup",
+          model: { providerID: "test-provider", modelID: "test-model" },
+          agent: "test-agent",
+        },
+        parts: [{ type: "text", text: "use the discovery skill", synthetic: false }],
+      } as any
+    );
+
+    assert.equal(client.prompts.length, 2);
+    assert.ok(client.prompts.some((prompt) => /<available-skills>/.test(prompt.text)));
+    assert.ok(client.prompts.some((prompt) => /You have superpowers\./.test(prompt.text)));
+
+    await plugin.event({ event: { type: "session.compacted", properties: { sessionID: "session-startup" } } } as any);
+
+    await plugin["chat.message"](
+      {},
+      {
+        message: {
+          sessionID: "session-startup",
+          model: { providerID: "test-provider", modelID: "test-model" },
+          agent: "test-agent",
+        },
+        parts: [{ type: "text", text: "run the script skill", synthetic: false }],
+      } as any
+    );
+
+    assert.ok(client.prompts.length >= 2);
+  });
+
+  test("skill tools load content and execute scripts", async () => {
+    const { SkillsPlugin } = await import("../../src");
+
+    const client = createMockOpencodeClient();
+    const shell = createShellRecorder();
+    const plugin = await SkillsPlugin({ client: client.client, $: shell.shell, directory: workspace.projectRoot } as any);
+
+    const loaded = await plugin.tool.use_skill.execute({ skill: "scripted-skill" }, { sessionID: "session-tools" } as any);
+    assert.match(loaded, /loaded\./i);
+    assert.equal(client.prompts.at(-1)?.text.includes("<skill name=\"scripted-skill\">"), true);
+
+    const fileLoaded = await plugin.tool.read_skill_file.execute(
+      { skill: "scripted-skill", filename: "docs/reference.md" },
+      { sessionID: "session-tools" } as any
+    );
+    assert.match(fileLoaded, /loaded/i);
+
+    const output = await plugin.tool.run_skill_script.execute(
+      { skill: "scripted-skill", script: "bin/echo.sh", arguments: ["hello"] },
+      { sessionID: "session-tools" } as any
+    );
+    assert.match(output, /hello/);
+    assert.equal(shell.calls[0]?.cwd, workspace.scriptedSkillPath);
+  });
+
+  /**
+   * Regression coverage for the skill-loading callback wiring (PR 1 of
+   * `fix-skill-loading-regression`). Asserts the end-to-end behavior at the
+   * integration layer:
+   *   - after `use_skill`, `onSkillLoaded` is observable via the session's
+   *     loaded-skill state
+   *   - the same keyword in a subsequent chat.message does NOT re-trigger
+   *     a <skill-evaluation-required> injection for the loaded skill
+   *
+   * With the regression, the loader does not update loaded-skill state so
+   * the matcher re-emits an evaluation prompt for the already-loaded skill.
+   */
+  test("use_skill callback updates loaded-skill state and prevents duplicate match injection (PR 1)", async () => {
+    const { SkillsPlugin } = await import("../../src");
+
+    const client = createMockOpencodeClient();
+    const shell = createShellRecorder();
+    const plugin = await SkillsPlugin({
+      client: client.client,
+      $: shell.shell,
+      directory: workspace.projectRoot,
+    } as any);
+
+    const SESSION = "session-loaded-state";
+
+    // Bootstrap the session: first message injects <available-skills>.
+    await plugin["chat.message"](
+      {},
+      {
+        message: {
+          sessionID: SESSION,
+          model: { providerID: "test-provider", modelID: "test-model" },
+          agent: "test-agent",
+        },
+        parts: [{ type: "text", text: "first message", synthetic: false }],
+      } as any,
+    );
+    const promptsAfterBootstrap = client.prompts.length;
+
+    // Load scripted-skill via use_skill.
+    const loadResult = await plugin.tool.use_skill.execute(
+      { skill: "scripted-skill" },
+      { sessionID: SESSION } as any,
+    );
+    assert.match(loadResult, /loaded\./i, "use_skill reports a successful load");
+    assert.ok(
+      client.prompts.slice(promptsAfterBootstrap).some((p) =>
+        /<skill name="scripted-skill">/.test(p.text),
+      ),
+      "use_skill injects the skill content into the session",
+    );
+
+    // Subsequent chat.message with a keyword that also matches scripted-skill.
+    // Other skills may legitimately match too, but scripted-skill MUST be
+    // filtered out by the loaded-skill set after the fix. Before the fix,
+    // scripted-skill appears because loadedSkillsPerSession was never updated.
+    const promptsBeforeRepeat = client.prompts.length;
+    await plugin["chat.message"](
+      {},
+      {
+        message: {
+          sessionID: SESSION,
+          model: { providerID: "test-provider", modelID: "test-model" },
+          agent: "test-agent",
+        },
+        parts: [{ type: "text", text: "use the script skill", synthetic: false }],
+      } as any,
+    );
+    const newPrompts = client.prompts.slice(promptsBeforeRepeat);
+    const evaluationInjections = newPrompts.filter((p) =>
+      /<skill-evaluation-required>/.test(p.text),
+    );
+    for (const prompt of evaluationInjections) {
+      assert.doesNotMatch(
+        prompt.text,
+        /^- scripted-skill:/m,
+        "loaded-skill state must suppress scripted-skill from re-injection",
+      );
+    }
+  });
+});
+
+/**
+ * `GetAvailableSkills` with the new `keywords` parameter and the safe-input
+ * `query` path. These are RED tests for PR2 — the current tool has no
+ * `keywords` arg, and the existing `new RegExp(args.query)` path crashes
+ * on regex-special characters. The fixture skills in
+ * `tests/fixtures/skills/project/.opencode/skills/{go-tester,rust-tester}`
+ * carry `metadata.tags` so the search layer can filter against them.
+ */
+describe("GetAvailableSkills with keywords", () => {
+  let workspace: Awaited<ReturnType<typeof createFixtureWorkspace>>;
+
+  beforeEach(async () => {
+    workspace = await createFixtureWorkspace();
+  });
+
+  afterEach(async () => {
+    if (workspace) {
+      await workspace.cleanup();
+    }
+  });
+
+  test("keywords=['go'] returns only skills whose tags include 'go'", async () => {
+    const { SkillsPlugin } = await import("../../src");
+    const client = createMockOpencodeClient();
+    const shell = createShellRecorder();
+    const plugin = await SkillsPlugin({
+      client: client.client,
+      $: shell.shell,
+      directory: workspace.projectRoot,
+    } as any);
+
+    const result = await plugin.tool.get_available_skills.execute(
+      { keywords: ["go"] } as any,
+      { sessionID: "keywords-test" } as any
+    );
+
+    assert.match(result, /go-tester/);
+    assert.doesNotMatch(result, /rust-tester/);
+  });
+
+  test("query + keywords applies both filters", async () => {
+    const { SkillsPlugin } = await import("../../src");
+    const client = createMockOpencodeClient();
+    const shell = createShellRecorder();
+    const plugin = await SkillsPlugin({
+      client: client.client,
+      $: shell.shell,
+      directory: workspace.projectRoot,
+    } as any);
+
+    const result = await plugin.tool.get_available_skills.execute(
+      { query: "tester", keywords: ["go"] } as any,
+      { sessionID: "combined-test" } as any
+    );
+
+    // Only `go-tester` is tagged "go"; "rust-tester" is filtered out.
+    assert.match(result, /go-tester/);
+    assert.doesNotMatch(result, /rust-tester/);
+  });
+
+  test("query with regex-special characters does not throw", async () => {
+    const { SkillsPlugin } = await import("../../src");
+    const client = createMockOpencodeClient();
+    const shell = createShellRecorder();
+    const plugin = await SkillsPlugin({
+      client: client.client,
+      $: shell.shell,
+      directory: workspace.projectRoot,
+    } as any);
+
+    // The legacy implementation crashed here because `new RegExp("(test+", "i")`
+    // throws — the unescaped `(` and `+` are invalid regex syntax. After
+    // the search-layer wiring, the tool must produce a string result
+    // (matches or a clean no-match) without throwing. The fuzzy scorer
+    // legitimately matches "go-tester" and "rust-tester" against the
+    // substring "test" inside the escaped token, so a non-empty result
+    // is expected and acceptable.
+    const result = await plugin.tool.get_available_skills.execute(
+      { query: "(test+" } as any,
+      { sessionID: "regex-test" } as any
+    );
+
+    assert.ok(typeof result === "string", "returns a string result");
+  });
+});
+
+/**
+ * PR 2 plugin refactor coverage at the integration level: confirms the
+ * event hook keeps working with the closure-scoped state. The event
+ * handler reads `event.properties.info.id` (PR 1 had a typo where it
+ * reused the `session.compacted` variable).
+ */
+describe("plugin event hooks survive the PR 2 refactor", () => {
+  let workspace: Awaited<ReturnType<typeof createFixtureWorkspace>>;
+
+  beforeEach(async () => {
+    workspace = await createFixtureWorkspace();
+  });
+
+  afterEach(async () => {
+    if (workspace) await workspace.cleanup();
+  });
+
+  test("session.deleted reads event.properties.info.id (no closure-scope leakage)", async () => {
+    const { SkillsPlugin } = await import("../../src");
+    const client = createMockOpencodeClient();
+    const shell = createShellRecorder();
+    const plugin = await SkillsPlugin({ client: client.client, $: shell.shell, directory: workspace.projectRoot } as any);
+
+    // Bootstrap, then delete — must not throw the "Cannot find name 'sessionID'"
+    // bug that the original (pre-PR2) code would hit if a prior event
+    // handler hadn't set `sessionID` first.
+    await plugin["chat.message"](
+      {},
+      {
+        message: {
+          sessionID: "session-A",
+          model: { providerID: "test-provider", modelID: "test-model" },
+          agent: "test-agent",
+        },
+        parts: [{ type: "text", text: "first message", synthetic: false }],
+      } as any,
+    );
+
+    await assert.doesNotReject(
+      plugin.event({ event: { type: "session.deleted", properties: { info: { id: "session-A" } } } } as any),
+      "session.deleted must resolve event.properties.info.id from its own branch",
+    );
+  });
+});