Module: Tina4::AI

Defined in:
lib/tina4/ai.rb

Overview

Tina4 AI -- Install AI coding assistant context files.

Simple menu-driven installer for AI tool context files. The user picks which tools they use, we install the appropriate files.

selection = Tina4::AI.show_menu(".")
Tina4::AI.install_selected(".", selection)

Constant Summary collapse

AI_TOOLS =

Ordered list of supported AI tools

[
  { name: "claude-code", description: "Claude Code", context_file: "CLAUDE.md", config_dir: ".claude" },
  { name: "cursor", description: "Cursor", context_file: ".cursorules", config_dir: ".cursor" },
  { name: "copilot", description: "GitHub Copilot", context_file: ".github/copilot-instructions.md", config_dir: ".github" },
  { name: "windsurf", description: "Windsurf", context_file: ".windsurfrules", config_dir: nil },
  { name: "aider", description: "Aider", context_file: "CONVENTIONS.md", config_dir: nil },
  { name: "cline", description: "Cline", context_file: ".clinerules", config_dir: nil },
  { name: "codex", description: "OpenAI Codex", context_file: "AGENTS.md", config_dir: nil }
].freeze
DEV_SKILL =

── Skill files (the SKILL.md system) ───────────────────────────────── tina4 ai installs the actual skills -- not just a CLAUDE.md pointer to them -- into BOTH the project (.claude/skills, so they travel with the repo) AND the user's global ~/.claude/skills (so they're available in every project). A Ruby project needs the ruby developer skill plus the two shared skills. As of 3.13.59 the developer skill is split per language: the ruby dev skill ships from the tina4-ruby release tag, while tina4-js + tina4-maintainer are the canonical shared copies served from tina4-python. Mirrors the canonical install-skills.sh.

"tina4-developer-ruby"
DEV_REFS = 
%w[
  auth-and-services.md data-and-orm.md deployment.md
  routes-and-api.md templates-and-frontend.md realtime.md
].freeze
SKILLS =

skill name => { repo:, refs: [reference files] }

{
  DEV_SKILL => { repo: "tina4-ruby", refs: DEV_REFS },
  "tina4-js" => {
    repo: "tina4-python",
    refs: %w[html-and-components.md signals-and-reactivity.md persistence.md rtc.md]
  },
  "tina4-maintainer" => {
    repo: "tina4-python",
    refs: %w[cli-and-deployment.md frond-and-frontend.md routing-and-orm.md subsystems.md]
  }
}.freeze
TRANSIENT_HTTP_CODES = 
%w[429 500 502 503 504].freeze
OLD_FRAMEWORK_HEADERS =

Headers the pre-v3.13.9 installer wrote at the top of CLAUDE.md.

[
  "# Tina4 Python",
  "# Tina4 PHP",
  "# Tina4 Ruby",
  "# CLAUDE.md -- AI Developer Guide for tina4-nodejs",
  "# CLAUDE.md — AI Developer Guide for tina4-nodejs",
].freeze

Class Method Summary collapse

Class Method Details

.fetch_and_retry(url, limit, retries) ⇒ Object 



121
122
123
124
 
# File 'lib/tina4/ai.rb', line 121

def fetch_and_retry(url, limit, retries)
  sleep(0.5)
  fetch_bytes(url, limit, retries - 1)
end

.fetch_bytes(url, limit = 5, retries = 2) ⇒ String?

Fetch the bytes at url, following up to limit redirects. Returns nil on any network/HTTP failure so the caller can skip gracefully.

MEASURED 2026-08-13 on the real suite (not a mock): install_skills makes up to 18 sequential HTTPS calls (3 skills x 2 targets x (1 SKILL.md + refs)) to raw.githubusercontent.com, and a single transient timeout/reset on any one of them silently dropped that whole skill - installed came back missing "tina4-maintainer" with no other symptom. A short retry on the TRANSPORT-level failure modes only (never on a clean HTTP response, which is a real answer, not a glitch) is the fix a real end user running tina4 ai needs too, not just this suite.

Parameters:

  • url (String)
  • limit (Integer) (defaults to: 5) —

    max redirects to follow

  • retries (Integer) (defaults to: 2) —

    transient-failure retries before giving up

Returns:

  • (String, nil) 


87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/tina4/ai.rb', line 87

def fetch_bytes(url, limit = 5, retries = 2)
  return nil if limit <= 0

  uri = URI.parse(url)
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = (uri.scheme == "https")
  http.open_timeout = 15
  http.read_timeout = 15

  response = http.get(uri.request_uri)
  case response
  when Net::HTTPSuccess
    return response.body
  when Net::HTTPRedirection
    location = response["location"]
    return location ? fetch_bytes(location, limit - 1, retries) : nil
  end

  # Not a success or a redirect. A throttle/server hiccup (429 rate
  # limit, 502/503/504) is worth one retry; anything else (404, a real
  # 4xx) is a genuine answer - retrying would not change it.
  return fetch_and_retry(url, limit, retries) if retries.positive? && TRANSIENT_HTTP_CODES.include?(response.code)

  nil
rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED, SocketError, EOFError
  return nil unless retries.positive?

  fetch_and_retry(url, limit, retries)
rescue StandardError
  nil
end

.generate_context(tool_name = "claude-code") ⇒ String

Generate per-tool Tina4 Ruby context document.

Parameters:

  • tool_name (String) (defaults to: "claude-code") —

    AI tool name (default: "claude-code")

Returns:

  • (String) 


255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/tina4/ai.rb', line 255

def generate_context(tool_name = "claude-code")
  case tool_name
  when "claude-code"
    generate_claude_code_context
  when "cursor"
    generate_cursor_context
  when "copilot"
    generate_copilot_context
  when "windsurf"
    generate_windsurf_context
  when "aider"
    generate_aider_context
  when "cline"
    generate_cline_context
  when "codex"
    generate_codex_context
  else
    generate_claude_code_context
  end
end

.has_markers?(existing, start, finish) ⇒ Boolean

True iff both start and end markers appear in order.

Returns:

  • (Boolean) 


325
326
327
328
329
 
# File 'lib/tina4/ai.rb', line 325

def has_markers?(existing, start, finish)
  s_idx = existing.index(start)
  return false unless s_idx
  !existing.index(finish, s_idx + start.length).nil?
end

.install_all(root = ".") ⇒ Array<String>

Install context for all AI tools (non-interactive).

Parameters:

  • root (String) (defaults to: ".") —

    project root directory

Returns:

  • (Array<String>) —

    list of created/updated file paths



247
248
249
 
# File 'lib/tina4/ai.rb', line 247

def install_all(root = ".")
  install_selected(root, "all")
end

.install_claude_skills(root) ⇒ Array<String>

Install Claude Code skills + commands for a project.

Parameters:

  • root (String) —

    absolute project root path

Returns:

  • (Array<String>) —

    list of created/updated relative file paths



428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
 
# File 'lib/tina4/ai.rb', line 428

def install_claude_skills(root)
  created = []

  # Copy claude-commands if they exist (a local template shipped in the
  # gem, not a network fetch).
  framework_root = File.expand_path("../../..", __FILE__)
  commands_source = File.join(framework_root, "templates", "ai", "claude-commands")
  if Dir.exist?(commands_source)
    commands_dir = File.join(root, ".claude", "commands")
    FileUtils.mkdir_p(commands_dir)
    Dir.glob(File.join(commands_source, "*.md")).each do |skill_file|
      target = File.join(commands_dir, File.basename(skill_file))
      FileUtils.cp(skill_file, target)
      rel = target.sub("#{root}/", "")
      created << rel
    end
  end

  # Install the SKILL.md skills into the project AND the user's global
  # ~/.claude/skills, network-fetched from the release tag matching this
  # framework version. (The previous code copied from
  # framework_root/.claude/skills, which exists only in a dev/editable
  # checkout -- NOT in an installed gem, where .claude/skills sits outside
  # lib/ and is never packaged. So installed users got zero skill files,
  # only a CLAUDE.md pointer to skills that were never on disk.)
  install_skills(root).each do |skill|
    created << ".claude/skills/#{skill}/"
    puts "  \e[32m✓\e[0m Installed .claude/skills/#{skill}  (project + global)"
  end

  created
end

.install_for_tool(root, tool, context) ⇒ Object 



399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
 
# File 'lib/tina4/ai.rb', line 399

def install_for_tool(root, tool, context)
  created = []
  context_path = File.join(root, tool[:context_file])

  # Create directories
  if tool[:config_dir]
    FileUtils.mkdir_p(File.join(root, tool[:config_dir]))
  end
  FileUtils.mkdir_p(File.dirname(context_path))

  # v3.13.9: non-destructive write -- see write_or_merge below.
  action = write_or_merge(context_path, tool[:context_file], context)
  rel = context_path.sub("#{root}/", "")
  created << rel
  puts "  \e[32m✓\e[0m #{action} #{rel}"

  # Claude-specific extras
  if tool[:name] == "claude-code"
    skills = install_claude_skills(root)
    created.concat(skills)
  end

  created
end

.install_selected(root, selection) ⇒ Array<String>

Install context files for the selected tools.

Parameters:

  • root (String) —

    project root directory

  • selection (String) —

    comma-separated numbers like "1,2,3" or "all"

Returns:

  • (Array<String>) —

    list of created/updated file paths



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/tina4/ai.rb', line 210

def install_selected(root, selection)
  root_path = File.expand_path(root)
  created = []

  if selection.downcase == "all"
    indices = (0...AI_TOOLS.length).to_a
    do_tina4_ai = true
  else
    parts = selection.split(",").map(&:strip).reject(&:empty?)
    indices = []
    do_tina4_ai = false
    parts.each do |p|
      n = Integer(p) rescue next
      if n == 8
        do_tina4_ai = true
      elsif n >= 1 && n <= AI_TOOLS.length
        indices << (n - 1)
      end
    end
  end

  indices.each do |idx|
    tool = AI_TOOLS[idx]
    context = generate_context(tool[:name])
    files = install_for_tool(root_path, tool, context)
    created.concat(files)
  end

  install_tina4_ai if do_tina4_ai

  created
end

.install_skills(root = ".", targets = nil) ⇒ Array<String>

Install the Tina4 SKILL.md skills into the project AND the user's global ~/.claude/skills, network-fetched from the release tag matching this framework version. Returns the skills fully installed. Network-dependent -- a fetch failure skips that skill gracefully.

Parameters:

  • root (String) (defaults to: ".") —

    project root directory

  • targets (Array<String>, nil) (defaults to: nil) —

    .claude/skills dirs to write to; defaults to the project's + the user's global skills dir

Returns:

  • (Array<String>) —

    skill names that installed cleanly



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/tina4/ai.rb', line 135

def install_skills(root = ".", targets = nil)
  ref = skills_ref
  if targets.nil?
    targets = [
      File.join(File.expand_path(root), ".claude", "skills"),
      File.join(Dir.home, ".claude", "skills")
    ]
  end

  installed = []
  SKILLS.each do |skill, meta|
    base = "https://raw.githubusercontent.com/tina4stack/#{meta[:repo]}/#{ref}/.claude/skills"
    skill_ok = true

    targets.each do |dest|
      skill_dir = File.join(dest, skill)
      FileUtils.mkdir_p(File.join(skill_dir, "references"))

      data = fetch_bytes("#{base}/#{skill}/SKILL.md")
      if data.nil?
        skill_ok = false
        next
      end
      File.binwrite(File.join(skill_dir, "SKILL.md"), data)

      meta[:refs].each do |r|
        rd = fetch_bytes("#{base}/#{skill}/references/#{r}")
        File.binwrite(File.join(skill_dir, "references", r), rd) unless rd.nil?
      end
    end

    installed << skill if skill_ok
  end
  installed
end

.install_tina4_ai ⇒ Object

Install tina4-ai package (provides mdview for markdown viewing).



462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
 
# File 'lib/tina4/ai.rb', line 462

def install_tina4_ai
  puts "  Installing tina4-ai tools..."
  %w[pip3 pip].each do |cmd|
    next unless system("which #{cmd} > /dev/null 2>&1")

    result = `#{cmd} install --upgrade tina4-ai 2>&1`
    # Subprocess output is ASCII-8BIT — force UTF-8 with byte replacement
    # so non-ASCII content (often emitted by pip on locale mismatch)
    # doesn't crash String#strip with Encoding::CompatibilityError.
    safe_result = result.dup.force_encoding("UTF-8")
    unless safe_result.valid_encoding?
      safe_result = safe_result.encode("UTF-8", "UTF-8", invalid: :replace, undef: :replace, replace: "?")
    end
    if $?.success?
      puts "  \e[32m✓\e[0m Installed tina4-ai (mdview)"
      return
    else
      puts "  \e[33m!\e[0m #{cmd} failed: #{safe_result.strip[0..100]}"
    end
  end
  puts "  \e[33m!\e[0m Python/pip not available -- skip tina4-ai"
end

.is_installed(root, tool) ⇒ Boolean

Check if a tool's context file already exists.

Parameters:

  • root (String) —

    project root directory

  • tool (Hash) —

    tool entry from AI_TOOLS

Returns:

  • (Boolean) 


176
177
178
 
# File 'lib/tina4/ai.rb', line 176

def is_installed(root, tool)
  File.exist?(File.join(File.expand_path(root), tool[:context_file]))
end

.looks_like_old_framework_install?(existing) ⇒ Boolean

Returns:

  • (Boolean) 


353
354
355
356
 
# File 'lib/tina4/ai.rb', line 353

def looks_like_old_framework_install?(existing)
  head = existing.lstrip[0, 400] || ""
  OLD_FRAMEWORK_HEADERS.any? { |h| head.start_with?(h) }
end

.markers_for(context_file) ⇒ Object

Return [start, end] markers for the given context file.



291
292
293
294
295
296
297
 
# File 'lib/tina4/ai.rb', line 291

def markers_for(context_file)
  if context_file.downcase.end_with?(".md")
    ["<!-- tina4-skills:start -->", "<!-- tina4-skills:end -->"]
  else
    ["# tina4-skills:start", "# tina4-skills:end"]
  end
end

.replace_marker_block(existing, block, start, finish) ⇒ Object

Replace the bracketed block in existing with block.



332
333
334
335
336
337
338
339
340
341
342
 
# File 'lib/tina4/ai.rb', line 332

def replace_marker_block(existing, block, start, finish)
  s_idx = existing.index(start)
  return existing.rstrip + "\n\n" + block + "\n" unless s_idx
  e_idx = existing.index(finish, s_idx + start.length)
  return existing.rstrip + "\n\n" + block + "\n" unless e_idx
  before = existing[0...s_idx].rstrip
  after = existing[(e_idx + finish.length)..].sub(/\A\n+/, "")
  glue_before = before.empty? ? "" : "\n\n"
  glue_after = after.empty? ? "\n" : "\n" + after
  "#{before}#{glue_before}#{block}#{glue_after}"
end

.show_menu(root = ".") ⇒ String

Print the numbered menu and return user input.

Parameters:

  • root (String) (defaults to: ".") —

    project root directory (default: ".")

Returns:

  • (String) —

    user input (comma-separated numbers or "all")



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/tina4/ai.rb', line 184

def show_menu(root = ".")
  root = File.expand_path(root)
  green = "\e[32m"
  reset = "\e[0m"

  puts "\n  Tina4 AI Context Installer\n"
  AI_TOOLS.each_with_index do |tool, i|
    marker = is_installed(root, tool) ? "  #{green}[installed]#{reset}" : ""
    puts format("  %d. %-20s %s%s", i + 1, tool[:description], tool[:context_file], marker)
  end

  # tina4-ai tools option
  tina4_ai_installed = system("which mdview > /dev/null 2>&1")
  marker = tina4_ai_installed ? "  #{green}[installed]#{reset}" : ""
  puts "  8. Install tina4-ai tools  (requires Python)#{marker}"
  puts

  print "  Select (comma-separated, or 'all'): "
  $stdin.gets&.strip || ""
end

.skill_block(context_file) ⇒ Object

Return the marker-bracketed Tina4 skill registration block.



300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/tina4/ai.rb', line 300

def skill_block(context_file)
  start, finish = markers_for(context_file)
  body = if context_file.downcase.end_with?(".md")
    "## Tina4 Skills\n\n" \
    "When working on this Tina4 project, these skills give the assistant project-aware behaviour:\n\n" \
    "- **#{DEV_SKILL}** -- Read `.claude/skills/#{DEV_SKILL}/SKILL.md` before building features.\n" \
    "- **tina4-js** -- Read `.claude/skills/tina4-js/SKILL.md` for frontend work.\n" \
    "- **tina4-maintainer** -- Read `.claude/skills/tina4-maintainer/SKILL.md` for framework-level changes.\n\n" \
    "If Tina4 behaves differently from what these skills describe, that is a bug in the skill. " \
    "Tell the developer, then report it at https://tina4.com/report-a-skill " \
    "(or open an issue on the matching tina4stack/* GitHub repo).\n\n" \
    "See https://tina4.com for full docs."
  else
    "Tina4 Skills -- read these files before working on this project:\n" \
    "  .claude/skills/#{DEV_SKILL}/SKILL.md   (feature development)\n" \
    "  .claude/skills/tina4-js/SKILL.md          (frontend / tina4-js)\n" \
    "  .claude/skills/tina4-maintainer/SKILL.md  (framework-level changes)\n" \
    "Found a skill that disagrees with how Tina4 actually behaves? Tell the developer,\n" \
    "then report it at https://tina4.com/report-a-skill\n" \
    "Docs: https://tina4.com"
  end
  "#{start}\n#{body}\n#{finish}"
end

.skills_ref ⇒ String

Release tag to pull skills from -- the installed framework version, overridable with TINA4_SKILLS_REF (e.g. to test a branch / tag).

Returns:

  • (String) 


61
62
63
64
65
66
67
68
 
# File 'lib/tina4/ai.rb', line 61

def skills_ref
  ref = ENV["TINA4_SKILLS_REF"]
  return ref if ref && !ref.strip.empty?
  return Tina4::VERSION if defined?(Tina4::VERSION) && Tina4::VERSION
  "main"
rescue StandardError
  "main"
end

.write_or_merge(context_path, context_file, framework_guide) ⇒ Object

Write the context file non-destructively. Returns a human-readable action verb for the caller's log line.

Four branches:

1. Doesn't exist  -> write framework guide + skill block
2. Has markers    -> refresh just the skill block (idempotent)
3. Old header     -> migrate: replace old dump with new guide + block
4. User content   -> append the skill block, preserve everything else


366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/tina4/ai.rb', line 366

def write_or_merge(context_path, context_file, framework_guide)
  # Force UTF-8 — CLAUDE.md and the framework guide both contain
  # non-ASCII (em-dashes, ✓, etc.). Without this, File.read may
  # return ASCII-8BIT and string concat raises CompatibilityError.
  block = skill_block(context_file).dup.force_encoding("UTF-8")
  guide = framework_guide.dup.force_encoding("UTF-8")
  start, finish = markers_for(context_file)

  unless File.exist?(context_path)
    File.write(context_path, guide.rstrip + "\n\n" + block + "\n", encoding: "UTF-8")
    return "Installed"
  end

  existing = File.read(context_path, encoding: "UTF-8")

  if has_markers?(existing, start, finish)
    File.write(context_path, replace_marker_block(existing, block, start, finish), encoding: "UTF-8")
    return "Refreshed skill block in"
  end

  if looks_like_old_framework_install?(existing)
    head = existing.lstrip
    preamble = existing[0, existing.length - head.length] || ""
    new_content = (preamble.strip.empty? ? "" : preamble.rstrip + "\n\n") +
                  guide.rstrip + "\n\n" + block + "\n"
    File.write(context_path, new_content, encoding: "UTF-8")
    return "Migrated (replaced old framework dump in)"
  end

  File.write(context_path, existing.rstrip + "\n\n" + block + "\n", encoding: "UTF-8")
  "Appended skill block to"
end