Putiorのインストール

Install the putior R package and its optional dependencies so the annotation-to-diagram pipeline is ready to use.

使用タイミング

• Setting up putior for the first time in a project or environment
• Preparing a machine for workflow visualization tasks
• A downstream skill (analyze-codebase-workflow, generate-workflow-diagram) requires putior to be installed
• Restoring an environment after an R version upgrade or renv wipe

入力

• 必須: Access to an R installation (>= 4.1.0)
• 任意: Whether to install from CRAN (default) or GitHub dev version
• 任意: Which optional dependency groups to install: MCP (mcptools, ellmer), interactive (shiny, shinyAce), logging (logger), ACP (plumber2)

手順

ステップ1: Verify R Installation

Confirm R is available and meets the minimum version requirement.

R.Version()$version.string
# Must be >= 4.1.0

# From WSL with Windows R
"/mnt/c/Program Files/R/R-4.5.2/bin/Rscript.exe" -e "cat(R.version.string)"

期待結果: R version string printed, >= 4.1.0.

失敗時: Install or upgrade R. On Windows, download from https://cran.r-project.org/bin/windows/base/. On Linux, use sudo apt install r-base.

ステップ2: Install putior

Install from CRAN (stable) or GitHub (dev).

# CRAN (recommended)
install.packages("putior")

# GitHub dev version (if latest features needed)
remotes::install_github("pjt222/putior")

期待結果: Package installs without errors. library(putior) loads silently.

失敗時: If CRAN installation fails with "not available for this version of R", use the GitHub version. If GitHub fails, check that remotes is installed: install.packages("remotes").

ステップ3: Install Optional Dependencies

Install optional packages based on required functionality.

# MCP server integration (for AI assistant access)
remotes::install_github("posit-dev/mcptools")
install.packages("ellmer")

# Interactive sandbox
install.packages("shiny")
install.packages("shinyAce")

# Structured logging
install.packages("logger")

# ACP server (agent-to-agent communication)
install.packages("plumber2")

期待結果: Each package installs without errors.

失敗時: For mcptools, ensure remotes is installed first. For system dependency errors on Linux, install the required libraries (e.g., sudo apt install libcurl4-openssl-dev for httr2 dependency).

ステップ4: Verify Installation

Run the basic pipeline to confirm everything works.

library(putior)

# Check package version
packageVersion("putior")

# Verify core functions are available
stopifnot(
  is.function(put),
  is.function(put_auto),
  is.function(put_diagram),
  is.function(put_generate),
  is.function(put_merge),
  is.function(put_theme)
)

# Test basic pipeline with a temp file
tmp <- tempfile(fileext = ".R")
writeLines("# put id:'test', label:'Hello putior'", tmp)
cat(put_diagram(put(tmp)))

期待結果: Mermaid flowchart code printed to console containing test and Hello putior.

失敗時: If put is not found, the package did not install correctly. Reinstall with install.packages("putior", dependencies = TRUE). If the diagram is empty, verify the temp file was created and the annotation syntax uses single quotes inside double quotes.

重要：カスタムパレットは MCP 経由では使用できません。 put_diagram の palette パラメータは、put_theme() で作成された putior_theme R オブジェクトを受け付けます。MCP は JSON 経由で通信するため、putior_theme のような R オブジェクトを MCP 境界を超えてシリアライズすることはできません。MCP 経由で put_diagram を呼び出す場合は、代わりに文字列ベースの theme パラメータを使用してください（例：theme = "viridis"）。カスタムパレットの場合は、R セッション内で直接 put_theme() と put_diagram(palette = ...) を呼び出してください。

主要なデフォルト値：すべてのスキャン関数（put()、put_auto()、put_generate()、put_merge()）はデフォルトで recursive = TRUE となっており、サブディレクトリを自動的にスキャンします。これは 0.2.0 以前のバージョン（デフォルトが FALSE だった）からの破壊的変更です。すべてのスキャン関数はまた、正規表現ベースのファイルフィルタリング用の exclude パラメータも受け付けます（例：put("./src/", exclude = "test_")）。

オプションの shiny パッケージがインストールされている場合は、インタラクティブサンドボックスを試してください：

putior::run_sandbox()

これにより、PUT アノテーション構文を実験してリアルタイムでレンダリングされた図を確認できるブラウザベースのエディタが起動します。

バリデーション

• library(putior) loads without errors
• packageVersion("putior") returns a valid version
• put() with a file containing a valid PUT annotation returns a data frame with one row
• put_diagram() produces Mermaid code starting with flowchart
• All requested optional dependencies load without errors

よくある落とし穴

• Wrong quote nesting: PUT annotations use single quotes inside the annotation: id:'name', not id:"name" (which conflicts with the comment string delimiter in some contexts).
• Missing Pandoc for vignettes: If you plan to build putior's vignettes locally, ensure RSTUDIO_PANDOC is set in .Renviron.
• renv isolation: If the project uses renv, you must install putior inside the renv library. Run renv::install("putior") instead of install.packages("putior").
• GitHub rate limits: Installing mcptools from GitHub may fail without a GITHUB_PAT. Set one via usethis::create_github_token().

関連スキル

• analyze-codebase-workflow — next step after installation to survey a codebase
• configure-putior-mcp — set up the MCP server after installing optional deps
• manage-renv-dependencies — manage putior within an renv environment
• configure-mcp-server — general MCP server configuration