npm - @softspark/ai-toolkit - Versions diffs - 2.5.0 → 2.6.2 - Mend

@softspark/ai-toolkit 2.5.0 → 2.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/AGENTS.md +1 -1
package/CHANGELOG.md +44 -0
package/README.md +8 -9
package/app/.claude-plugin/plugin.json +3 -2
package/app/ARCHITECTURE.md +11 -0
package/app/skills/hipaa-validate/SKILL.md +39 -23
package/app/skills/hipaa-validate/scripts/hipaa_scan.py +64 -7
package/bin/ai-toolkit.js +20 -5
package/kb/procedures/release-preparation-sop.md +6 -3
package/kb/reference/opencode-compatibility.md +161 -0
package/llms-full.txt +174 -4
package/llms.txt +1 -0
package/manifest.json +1 -1
package/package.json +6 -3
package/scripts/eject.py +5 -1
package/scripts/generate_opencode.py +117 -0
package/scripts/generate_opencode_agents.py +126 -0
package/scripts/generate_opencode_commands.py +158 -0
package/scripts/generate_opencode_json.py +133 -0
package/scripts/generate_opencode_plugin.py +169 -0
package/scripts/install_steps/ai_tools.py +117 -1
package/scripts/install_steps/install_state.py +1 -1

package/scripts/generate_opencode_agents.py ADDED Viewed

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Generate .opencode/agents/*.md files for opencode (https://opencode.ai).
+Each ai-toolkit agent becomes an opencode subagent with frontmatter:
+    ---
+    description: "..."
+    mode: subagent
+    ---
+    <body from agent file>
+Generated files are prefixed ``ai-toolkit-`` so they never collide with
+user-authored opencode agents and can be cleanly removed on uninstall.
+Usage:
+  python3 scripts/generate_opencode_agents.py [target-dir]
+Writes files to target-dir/.opencode/agents/.
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import agents_dir
+from frontmatter import frontmatter_field
+AGENT_PREFIX = "ai-toolkit-"
+def _agent_body(agent_file: Path) -> str:
+    """Return the markdown body of an agent file (content after frontmatter)."""
+    text = agent_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text.strip() + "\n"
+    # Skip first frontmatter block
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return text.strip() + "\n"
+    return parts[2].lstrip("\n")
+def _render_opencode_agent(agent_file: Path) -> str:
+    """Render a single opencode subagent .md file from an ai-toolkit agent."""
+    name = frontmatter_field(agent_file, "name")
+    description = frontmatter_field(agent_file, "description")
+    model = frontmatter_field(agent_file, "model")
+    color = frontmatter_field(agent_file, "color")
+    # Escape description for YAML quoted string
+    safe_desc = description.replace('"', "'")
+    lines: list[str] = ["---"]
+    lines.append(f'description: "{safe_desc}"')
+    lines.append("mode: subagent")
+    # opencode requires `provider/model-id` for the `model` field. ai-toolkit
+    # only stores a short alias (opus/sonnet/haiku) which is not mappable
+    # without assuming a provider, so we deliberately omit it — opencode falls
+    # back to the user's `default_agent` / top-level `model` config.
+    _ = model  # intentionally unused
+    if color:
+        lines.append(f"color: {color}")
+    lines.append("---")
+    lines.append("")
+    body = _agent_body(agent_file).rstrip()
+    if body:
+        lines.append(body)
+    lines.append("")
+    return "\n".join(lines)
+def _cleanup_stale(agents_out: Path) -> int:
+    """Remove stale ai-toolkit-* agent files whose source no longer exists."""
+    if not agents_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(agents_out.glob(f"{AGENT_PREFIX}*.md")):
+        source_name = f.stem[len(AGENT_PREFIX):]
+        source = agents_dir / f"{source_name}.md"
+        if not source.is_file():
+            f.unlink()
+            removed += 1
+    return removed
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write opencode agent files and return (written, removed_stale).
+    By default writes to ``target_dir/.opencode/agents/`` (project-local).
+    Pass ``config_root=~/.config/opencode`` for the global layout, which
+    lives directly under ``agents/`` (no ``.opencode/`` prefix).
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    agents_out = base / "agents"
+    agents_out.mkdir(parents=True, exist_ok=True)
+    written = 0
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        if not name or not description:
+            continue
+        out_path = agents_out / f"{AGENT_PREFIX}{name}.md"
+        out_path.write_text(_render_opencode_agent(agent_file), encoding="utf-8")
+        written += 1
+    removed = _cleanup_stale(agents_out)
+    return written, removed
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .opencode/agents/ ({written} agents"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+if __name__ == "__main__":
+    main()

package/scripts/generate_opencode_commands.py ADDED Viewed

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Generate .opencode/commands/*.md files for opencode (https://opencode.ai).
+User-invocable skills become opencode slash commands. Knowledge skills
+(``user-invocable: false``) are excluded — they load automatically via
+AGENTS.md context instead of `/` invocation.
+Generated commands use the required ``template`` frontmatter field.
+Files are prefixed ``ai-toolkit-`` for clean uninstall.
+opencode commands: https://opencode.ai/docs/commands/
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from codex_skill_adapter import build_codex_skill_text, is_codex_adapted_skill
+from emission import skills_dir
+from frontmatter import frontmatter_field
+COMMAND_PREFIX = "ai-toolkit-"
+def _skill_body(skill_file: Path) -> str:
+    """Return the markdown body of a skill (content after frontmatter).
+    For skills that rely on Claude-only orchestration primitives, route
+    through the Codex adapter so `Agent`/`TeamCreate`/`TaskCreate` get
+    rewritten to opencode-compatible delegation guidance. The adapter's
+    output is compatible with opencode's subagent model (``spawn_agent``
+    conventions, plan tracking) because both lack Claude primitives.
+    """
+    if is_codex_adapted_skill(skill_file):
+        adapted = build_codex_skill_text(skill_file)
+        # Strip the adapted frontmatter — we emit our own below
+        parts = adapted.split("---", 2)
+        return parts[2].lstrip("\n") if len(parts) >= 3 else adapted
+    text = skill_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text
+    parts = text.split("---", 2)
+    return parts[2].lstrip("\n") if len(parts) >= 3 else text
+def _render_opencode_command(skill_file: Path) -> str:
+    """Render a single opencode command .md file from a user-invocable skill."""
+    name = frontmatter_field(skill_file, "name")
+    description = frontmatter_field(skill_file, "description")
+    agent_field = frontmatter_field(skill_file, "agent")
+    # opencode does NOT read "body" — the prompt is entirely in the `template`
+    # frontmatter field. We embed the SKILL.md body as the template using a
+    # YAML block scalar (``|``) which preserves newlines without escaping.
+    body = _skill_body(skill_file).rstrip()
+    lines: list[str] = ["---"]
+    if description:
+        safe_desc = description.replace('"', "'")
+        lines.append(f'description: "{safe_desc}"')
+    if agent_field:
+        # opencode accepts an `agent` frontmatter field pointing at a subagent
+        lines.append(f"agent: {_map_agent_name(agent_field)}")
+    lines.append("template: |")
+    for tpl_line in body.splitlines() or [""]:
+        lines.append(f"  {tpl_line}" if tpl_line else "  ")
+    lines.append("---")
+    lines.append("")
+    return "\n".join(lines)
+def _map_agent_name(value: str) -> str:
+    """Map ai-toolkit agent names to opencode subagent names.
+    Our opencode agents are installed with the ``ai-toolkit-`` prefix by
+    ``generate_opencode_agents.py``, so rewrite here for consistency.
+    """
+    value = value.strip()
+    if not value:
+        return value
+    if value.startswith(COMMAND_PREFIX):
+        return value
+    return f"{COMMAND_PREFIX}{value}"
+def _is_user_invocable(skill_file: Path) -> bool:
+    """Return True if the skill should be exposed as a `/` command."""
+    invocable = frontmatter_field(skill_file, "user-invocable")
+    if invocable:
+        return invocable.lower() not in ("false", "0", "no")
+    # Absence + `disable-model-invocation: true` = task skill (user-invocable)
+    disable_model = frontmatter_field(skill_file, "disable-model-invocation")
+    if disable_model and disable_model.lower() in ("true", "1", "yes"):
+        return True
+    # Default: NOT invocable — avoids exposing knowledge skills as commands
+    return False
+def _cleanup_stale(commands_out: Path) -> int:
+    """Remove stale ai-toolkit-* command files whose source no longer exists or is no longer invocable."""
+    if not commands_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(commands_out.glob(f"{COMMAND_PREFIX}*.md")):
+        source_name = f.stem[len(COMMAND_PREFIX):]
+        source = skills_dir / source_name / "SKILL.md"
+        if not source.is_file() or not _is_user_invocable(source):
+            f.unlink()
+            removed += 1
+    return removed
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write opencode command files and return (written, removed_stale).
+    By default writes to ``target_dir/.opencode/commands/`` (project-local).
+    Pass ``config_root=~/.config/opencode`` for the global layout, which
+    lives directly under ``commands/`` (no ``.opencode/`` prefix).
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    commands_out = base / "commands"
+    commands_out.mkdir(parents=True, exist_ok=True)
+    written = 0
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if skill_dir.name.startswith("_"):
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        if not _is_user_invocable(skill_file):
+            continue
+        name = frontmatter_field(skill_file, "name")
+        if not name:
+            continue
+        out_path = commands_out / f"{COMMAND_PREFIX}{name}.md"
+        out_path.write_text(_render_opencode_command(skill_file), encoding="utf-8")
+        written += 1
+    removed = _cleanup_stale(commands_out)
+    return written, removed
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .opencode/commands/ ({written} commands"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+if __name__ == "__main__":
+    main()

package/scripts/generate_opencode_json.py ADDED Viewed

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Merge MCP servers from .mcp.json into opencode.json for opencode.
+opencode MCP config: https://opencode.ai/docs/mcp-servers/
+Schema per server:
+  Local:  {"type": "local",  "command": [...], "enabled": true, "environment": {...}}
+  Remote: {"type": "remote", "url": "...",      "enabled": true, "headers": {...}}
+Our canonical source is .mcp.json (Claude-style) with:
+  {"mcpServers": {"name": {"command": "...", "args": [...], "env": {...}}}}
+  or: {"name": {"url": "..."}} for remote.
+We translate into opencode's shape and merge under the ``mcp`` key.
+All non-``mcp`` keys are preserved verbatim — idempotent on re-run.
+Usage:
+  python3 scripts/generate_opencode_json.py [target-dir]
+"""
+from __future__ import annotations
+import copy
+import json
+import sys
+from pathlib import Path
+SCHEMA_URL = "https://opencode.ai/config.json"
+def _load_json(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return data
+def _write_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+def _translate_server(name: str, server: dict) -> dict:
+    """Translate a Claude-style server entry into opencode's shape."""
+    out: dict = {}
+    if "url" in server:
+        out["type"] = "remote"
+        out["url"] = server["url"]
+        if "headers" in server and isinstance(server["headers"], dict):
+            out["headers"] = copy.deepcopy(server["headers"])
+    elif "command" in server:
+        out["type"] = "local"
+        cmd = server["command"]
+        args = server.get("args") or []
+        if isinstance(cmd, list):
+            out["command"] = list(cmd) + list(args)
+        else:
+            out["command"] = [cmd, *args]
+        env = server.get("env") or server.get("environment")
+        if isinstance(env, dict) and env:
+            out["environment"] = copy.deepcopy(env)
+    else:
+        # Unknown shape — preserve as-is so opencode can report the error
+        out = copy.deepcopy(server)
+        out.setdefault("type", "local")
+    out.setdefault("enabled", True)
+    if "timeout" in server:
+        out["timeout"] = server["timeout"]
+    return out
+def _read_mcp_servers(project_dir: Path) -> dict:
+    """Read canonical .mcp.json and return the servers map.
+    Returns {} when no .mcp.json exists (non-fatal).
+    """
+    config = project_dir / ".mcp.json"
+    if not config.is_file():
+        return {}
+    data = _load_json(config)
+    servers = data.get("mcpServers", {})
+    if not isinstance(servers, dict):
+        return {}
+    return servers
+def merge_into_opencode_json(
+    target_dir: Path, output_path: Path | None = None
+) -> tuple[Path, int]:
+    """Merge .mcp.json servers into an opencode.json file.
+    Reads ``target_dir/.mcp.json`` as the canonical source. By default
+    writes to ``target_dir/opencode.json`` (project-local). Pass
+    ``output_path=~/.config/opencode/opencode.json`` for the global layout.
+    Returns (path, server_count). If no .mcp.json exists, still ensures
+    the output has the $schema key set (creates a minimal file).
+    """
+    servers = _read_mcp_servers(target_dir)
+    path = output_path if output_path is not None else target_dir / "opencode.json"
+    data = _load_json(path)
+    data.setdefault("$schema", SCHEMA_URL)
+    if servers:
+        bucket = data.setdefault("mcp", {})
+        if not isinstance(bucket, dict):
+            raise ValueError(f"{path} has invalid 'mcp' data (expected object)")
+        for name, entry in servers.items():
+            if not isinstance(entry, dict):
+                continue
+            bucket[name] = _translate_server(name, entry)
+    _write_json(path, data)
+    return path, len(servers)
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    path, count = merge_into_opencode_json(target)
+    rel = path.relative_to(target) if path.is_relative_to(target) else path
+    if count:
+        print(f"Generated: {rel} ({count} MCP server(s) merged)")
+    else:
+        print(f"Generated: {rel} (no MCP servers; .mcp.json not found)")
+if __name__ == "__main__":
+    main()

package/scripts/generate_opencode_plugin.py ADDED Viewed

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Generate the ai-toolkit opencode plugin at ``.opencode/plugins/ai-toolkit-hooks.js``.
+opencode plugins are JS/TS modules with a NAMED export that receive a
+context (``$``, ``project``, ``client``, ``directory``, ``worktree``) and
+return a hooks object. Docs: https://opencode.ai/docs/plugins/
+This generator emits a single-file plugin that bridges ai-toolkit's
+shared Bash hooks (``$HOME/.softspark/ai-toolkit/hooks/*.sh``) to
+opencode lifecycle events. Coverage map:
+  opencode event              -> ai-toolkit Bash hook(s)
+  ---------------------------------------------------------------
+  session.created             -> session-start.sh + session-context.sh + mcp-health.sh
+  session.compacted           -> pre-compact.sh + pre-compact-save.sh
+  session.deleted             -> session-end.sh + save-session.sh
+  message.updated             -> user-prompt-submit.sh + track-usage.sh
+  message.part.updated        -> user-prompt-submit.sh + track-usage.sh
+  tool.execute.before (bash)  -> guard-destructive.sh + commit-quality.sh
+  tool.execute.after          -> post-tool-use.sh
+  permission.asked            -> guard-destructive.sh
+  command.executed            -> post-tool-use.sh
+Security: hooks are invoked via ``$`` with the script path bound to a
+JS constant (no opencode-payload interpolation into the command). Event
+payloads are passed on stdin as JSON. Non-zero exit codes are logged to
+stderr; ``exit 2`` is preserved as a block signal for PreToolUse guards.
+Usage:
+  python3 scripts/generate_opencode_plugin.py [target-dir] [--config-root PATH]
+"""
+from __future__ import annotations
+import argparse
+import sys
+from pathlib import Path
+PLUGIN_BODY = r"""// ai-toolkit opencode plugin — bridges shared Bash hooks to opencode events.
+// Auto-generated by ai-toolkit. Do not edit by hand; re-run to update:
+//   ai-toolkit opencode-plugin
+// Docs: https://opencode.ai/docs/plugins/
+//
+// Hooks live at $HOME/.softspark/ai-toolkit/hooks/*.sh and are shared with
+// Claude Code and Codex CLI. This plugin invokes them via Bun's `$` shell
+// with the script path bound as a JS constant — no string interpolation of
+// opencode event payloads into the shell, so event data cannot inject
+// shell metacharacters. Payloads are passed on stdin as JSON.
+const HOOKS_DIR = `${process.env.HOME}/.softspark/ai-toolkit/hooks`;
+/** Invoke a Bash hook with a JSON payload on stdin. */
+async function runHook($, script, payload) {
+  const scriptPath = `${HOOKS_DIR}/${script}`;
+  try {
+    const input = JSON.stringify(payload ?? {});
+    const proc = $`bash ${scriptPath}`.env({
+      ...process.env,
+      AI_TOOLKIT_EVENT: payload?.event || "unknown",
+    });
+    proc.stdin.write(input);
+    proc.stdin.end();
+    const result = await proc.quiet().nothrow();
+    if (result.exitCode !== 0 && result.exitCode !== 2) {
+      // Exit 2 is the toolkit's "block" signal — pass through to opencode as a guard.
+      process.stderr.write(
+        `[ai-toolkit] ${script} exited ${result.exitCode}\n${result.stderr.toString()}`
+      );
+    }
+    return result.exitCode;
+  } catch (err) {
+    process.stderr.write(`[ai-toolkit] failed to run ${script}: ${err.message}\n`);
+    return 0;
+  }
+}
+export const AiToolkitHooks = async ({ $, project, directory, worktree }) => ({
+  event: async ({ event }) => {
+    const payload = { event: event.type, project, directory, worktree };
+    switch (event.type) {
+      case "session.created":
+        await runHook($, "session-start.sh", payload);
+        await runHook($, "session-context.sh", payload);
+        await runHook($, "mcp-health.sh", payload);
+        break;
+      case "session.compacted":
+        await runHook($, "pre-compact.sh", payload);
+        await runHook($, "pre-compact-save.sh", payload);
+        break;
+      case "session.deleted":
+        await runHook($, "session-end.sh", payload);
+        await runHook($, "save-session.sh", payload);
+        break;
+      case "message.updated":
+      case "message.part.updated":
+        await runHook($, "user-prompt-submit.sh", payload);
+        await runHook($, "track-usage.sh", payload);
+        break;
+      case "permission.asked":
+        await runHook($, "guard-destructive.sh", payload);
+        break;
+      case "command.executed":
+        await runHook($, "post-tool-use.sh", payload);
+        break;
+    }
+  },
+  "tool.execute.before": async (input, output) => {
+    const payload = {
+      event: "tool.execute.before",
+      tool: input?.tool,
+      args: output?.args,
+      project,
+    };
+    if (input?.tool === "bash") {
+      await runHook($, "guard-destructive.sh", payload);
+      await runHook($, "commit-quality.sh", payload);
+    }
+  },
+  "tool.execute.after": async (input, output) => {
+    const payload = {
+      event: "tool.execute.after",
+      tool: input?.tool,
+      result: output,
+      project,
+    };
+    await runHook($, "post-tool-use.sh", payload);
+  },
+});
+"""
+def generate(target_dir: Path, config_root: Path | None = None) -> Path:
+    """Write the opencode plugin file and return its path.
+    ``config_root`` lets the caller override the default project-local
+    layout. When omitted, writes to ``target_dir/.opencode/plugins/``.
+    Pass ``config_root=~/.config/opencode`` to lay down the plugin
+    globally at ``~/.config/opencode/plugins/ai-toolkit-hooks.js``.
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    plugins_dir = base / "plugins"
+    plugins_dir.mkdir(parents=True, exist_ok=True)
+    path = plugins_dir / "ai-toolkit-hooks.js"
+    path.write_text(PLUGIN_BODY, encoding="utf-8")
+    return path
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate opencode plugin")
+    parser.add_argument("target", nargs="?", default=".", help="Target directory")
+    parser.add_argument(
+        "--config-root",
+        type=Path,
+        default=None,
+        help="Override base (e.g. ~/.config/opencode for global install).",
+    )
+    args = parser.parse_args()
+    target = Path(args.target)
+    path = generate(target, config_root=args.config_root)
+    try:
+        rel = path.relative_to(target)
+    except ValueError:
+        rel = path
+    print(f"Generated: {rel}")
+if __name__ == "__main__":
+    main()