Merge branch 'main' into fix-mock

Author: ryoppippi

.claude/rules/nix-workflow.md

@@ -0,0 +1,84 @@
+# Nix Workflow
+
+This rule provides guidance on Nix usage in the StackOne AI Python SDK.
+
+## Development Environment
+
+The project uses `flake.nix` with flake-parts to define the development environment. Enter it with `nix develop`.
+
+### Adding Development Tools
+
+To add a new tool to the development environment, add it to `buildInputs` in `flake.nix`:
+
+```nix
+devShells.default = pkgs.mkShellNoCC {
+  buildInputs = with pkgs; [
+    uv
+    ty
+    just
+    nixfmt-rfc-style
+
+    # your new tool here
+    new-tool
+  ];
+};
+```
+
+### Treefmt and Git Hooks
+
+The flake includes:
+
+- **treefmt-nix**: Unified formatting (nixfmt, ruff, oxfmt)
+- **git-hooks.nix**: Pre-commit hooks (gitleaks, treefmt, ty)
+
+These are automatically installed when entering the dev shell.
+
+## CI Workflow
+
+CI uses `nix profile install` via the `.github/actions/setup-nix/action.yaml` composite action.
+
+### Adding Tools to CI Jobs
+
+Specify tools in the `tools` input of the setup-nix action:
+
+```yaml
+- name: Setup Nix
+  uses: ./.github/actions/setup-nix
+  with:
+    tools: uv ty just bun pnpm_10
+```
+
+The action installs packages using:
+
+```bash
+nix profile install --inputs-from . nixpkgs#tool1 nixpkgs#tool2
+```
+
+### CI Tool Configuration
+
+- **Default tools**: `uv ty just` (defined in action.yaml)
+- **Skip uv sync**: Set `skip-uv-sync: 'true'` for jobs that don't need Python dependencies
+
+### Example: Adding a New Tool to CI Job
+
+```yaml
+ci:
+  runs-on: ubuntu-latest
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        submodules: true
+    - name: Setup Nix
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: uv ty just new-tool
+    - name: Run Lint
+      run: just lint
+```
+
+## Notes
+
+- The project uses flake-parts for modular flake configuration
+- Git submodules are initialised automatically in dev shell and CI
+- MCP mock server dependencies (pnpm) are installed for testing

.github/actions/setup-nix/action.yaml

@@ -1,5 +1,14 @@
 name: "Setup Nix"
-description: "Install Nix and configure Cachix"
+description: "Install Nix and configure cache"
+inputs:
+  tools:
+    description: 'Space-separated list of nixpkgs packages to install (e.g., "uv ty just")'
+    required: false
+    default: "uv ty just"
+  skip-uv-sync:
+    description: "Skip uv sync step (useful for jobs that do not need Python dependencies)"
+    required: false
+    default: "false"
 runs:
   using: "composite"
   steps:
@@ -8,12 +17,34 @@ runs:
       with:
         github_access_token: ${{ github.token }}
 
-    - name: Setup Cachix (numtide)
-      uses: cachix/cachix-action@0fc020193b5a1fa3ac4575aa3a7d3aa6a35435ad # v16
-      with:
-        name: numtide
-        authToken: ""
+    - name: Install tools from nixpkgs
+      shell: bash
+      run: |
+        tools="${{ inputs.tools }}"
+        packages=""
+        for tool in $tools; do
+          packages="$packages nixpkgs#$tool"
+        done
+        nix profile install --inputs-from . $packages
+
+    - name: Initialise git submodules
+      if: inputs.skip-uv-sync != 'true'
+      shell: bash
+      run: |
+        # Only initialise if submodules exist but are not yet checked out
+        if [ -f .gitmodules ] && [ ! -f vendor/stackone-ai-node/package.json ]; then
+          git submodule update --init --recursive
+        fi
+
+    - name: Install Python dependencies
+      if: inputs.skip-uv-sync != 'true'
+      shell: bash
+      run: uv sync --all-extras
 
-    - name: Load Nix development environment
+    - name: Install MCP mock server dependencies
+      if: inputs.skip-uv-sync != 'true'
       shell: bash
-      run: nix develop --command true
+      run: |
+        if [ -f vendor/stackone-ai-node/package.json ]; then
+          cd vendor/stackone-ai-node && pnpm install --frozen-lockfile
+        fi

.github/workflows/ci.yaml

@@ -26,20 +26,18 @@ jobs:
 
       - name: Setup Nix
         uses: ./.github/actions/setup-nix
+        with:
+          tools: gitleaks
+          skip-uv-sync: "true"
 
       - name: Run Gitleaks
-        run: nix develop --command just gitleaks
+        run: gitleaks detect --source . --config .gitleaks.toml
 
   ci:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.13"]
-        include:
-          - python-version: "3.11"
-            sync-extras: "--all-extras"
-          - python-version: "3.13"
-            sync-extras: "--all-extras"
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: Checkout repository
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
@@ -48,18 +46,17 @@ jobs:
 
       - name: Setup Nix
         uses: ./.github/actions/setup-nix
-
-      - name: Install dependencies
-        run: nix develop --command just install ${{ matrix.sync-extras }}
+        with:
+          tools: uv ty just bun pnpm_10 typescript-go
 
       - name: Run Lint
-        run: nix develop --command just lint
+        run: just lint
 
       - name: Run Ty
-        run: nix develop --command just ty
+        run: just ty
 
       - name: Run Tests
-        run: nix develop --command just test
+        run: just test
 
   coverage:
     runs-on: ubuntu-latest
@@ -72,12 +69,11 @@ jobs:
 
       - name: Setup Nix
         uses: ./.github/actions/setup-nix
-
-      - name: Install dependencies
-        run: nix develop --command just install --all-extras
+        with:
+          tools: uv just bun pnpm_10 typescript-go
 
       - name: Run Tests with Coverage
-        run: nix develop --command just coverage
+        run: just coverage
 
       - name: Create Coverage Badge
         uses: jaywcjlove/coverage-badges-cli@4e8975aa2628e3329126e7eee36724d07ed86fda # v2.2.0

.github/workflows/nix-flake.yaml

@@ -26,8 +26,10 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
-      - name: Setup Nix
-        uses: ./.github/actions/setup-nix
+      - name: Install Nix
+        uses: cachix/install-nix-action@0b0e072294b088b73964f1d72dfdac0951439dbd # v31.8.4
+        with:
+          github_access_token: ${{ github.token }}
 
       - name: Check flake
-        run: nix flake check --all-systems --show-trace
+        run: nix flake check --all-systems --print-build-logs --show-trace

CLAUDE.md

@@ -15,6 +15,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | **git-workflow**             | All files           | Commit conventions, branch strategy, PR guidelines |
 | **development-workflow**     | All files           | Code style, file naming, project conventions       |
 | **release-please-standards** | All files           | Release versioning with release-please             |
+| **nix-workflow**             | All files           | Nix development environment and CI configuration   |
 | **no-relative-imports**      | `**/*.py`           | Enforce absolute imports in Python files           |
 | **package-installation**     | `**/pyproject.toml` | UV package management standards                    |
 | **uv-scripts**               | `scripts/**/*.py`   | Utility script standards with UV                   |

flake.lock

@@ -89,7 +89,7 @@
             };
           };
 
-          devShells.default = pkgs.mkShell {
+          devShells.default = pkgs.mkShellNoCC {
             buildInputs = with pkgs; [
               uv
               ty

flake.nix

@@ -3,7 +3,7 @@ name = "stackone-ai"
 version = "2.0.0"
 description = "agents performing actions on your SaaS"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.10"
 authors = [
     { name = "StackOne", email = "support@stackone.com" }
 ]
@@ -12,6 +12,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -77,7 +78,7 @@ markers = [
 
 [tool.ruff]
 line-length = 110
-target-version = "py311"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = [

pyproject.toml

@@ -23,7 +23,7 @@
 
 def _ensure_langgraph() -> None:
     try:
-        from langgraph import prebuilt as _  # noqa: F401  # ty: ignore[unresolved-import]
+        from langgraph import prebuilt as _  # noqa: F401
     except Exception as e:  # pragma: no cover
         raise ImportError(
             "LangGraph is not installed. Install with `pip install langgraph` or "
@@ -45,7 +45,7 @@ def to_tool_node(tools: Tools | Sequence[BaseTool], **kwargs: Any) -> Any:
     for inclusion in a graph.
     """
     _ensure_langgraph()
-    from langgraph.prebuilt import ToolNode  # ty: ignore[unresolved-import]
+    from langgraph.prebuilt import ToolNode
 
     langchain_tools = _to_langchain_tools(tools)
     return ToolNode(langchain_tools, **kwargs)
@@ -58,7 +58,7 @@ def to_tool_executor(tools: Tools | Sequence[BaseTool], **kwargs: Any) -> Any:
     This function now returns a ToolNode for compatibility.
     """
     _ensure_langgraph()
-    from langgraph.prebuilt import ToolNode  # ty: ignore[unresolved-import]
+    from langgraph.prebuilt import ToolNode
 
     langchain_tools = _to_langchain_tools(tools)
     return ToolNode(langchain_tools, **kwargs)
@@ -81,6 +81,6 @@ def create_react_agent(llm: Any, tools: Tools | Sequence[BaseTool], **kwargs: An
     `Tools` collection from this SDK.
     """
     _ensure_langgraph()
-    from langgraph.prebuilt import create_react_agent as _create  # ty: ignore[unresolved-import]
+    from langgraph.prebuilt import create_react_agent as _create  # ty: ignore[deprecated]
 
-    return _create(llm, _to_langchain_tools(tools), **kwargs)
+    return _create(llm, _to_langchain_tools(tools), **kwargs)  # ty: ignore[deprecated]

stackone_ai/integrations/langgraph.py

@@ -4,7 +4,7 @@
 import json
 import logging
 from collections.abc import Sequence
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from enum import Enum
 from typing import Annotated, Any, ClassVar, TypeAlias, cast
 from urllib.parse import quote
@@ -196,7 +196,7 @@ def execute(
             StackOneAPIError: If the API request fails
             ValueError: If the arguments are invalid
         """
-        datetime.now(UTC)
+        datetime.now(timezone.utc)
         feedback_options: JsonDict = {}
         result_payload: JsonDict | None = None
         response_status: int | None = None
@@ -266,7 +266,7 @@ def execute(
             status = "error"
             raise StackOneError(f"Request failed: {exc}") from exc
         finally:
-            datetime.now(UTC)
+            datetime.now(timezone.utc)
             metadata: JsonDict = {
                 "http_method": self._execute_config.method,
                 "url": url_used,