assistant 0.0.2 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57d148f4abcc7a6b10a3641ca2e75b0b4dfe0141a6536f062f1c8665f6bf5e2f
-  data.tar.gz: eed5fdf9f3e02724a342b109d8ef14e50b8b3fd359074ab5bb2475d1a08d88b0
+  metadata.gz: 6b4eab141f258e58024dcc2805a4030321835b45853cf915d8a8c48aa9849144
+  data.tar.gz: 354914c47054404c57ef636d46316e0ee8cb491305ab9c081a0628e4a30708c5
 SHA512:
-  metadata.gz: a067fca9874e1eae78d65c49fe3b583e186a8a19e0c08c31128683a7e351758f4c839edf0a70cb0bb2feb01521b55bc4d74782e4bfaf51272d7736daad44b517
-  data.tar.gz: 721b623f02e50b972bc9eb58ee25640e3d5092195c57d4e5f0f0c79bcb093eee82d49d1d0ebc84c5493af1a04755df6996c212edc055b35c21b6e68c99ff73d6
+  metadata.gz: ced1f45ddcc684272b2858aebead07ee968823cdf0c52bf71877cf283b1881fec66e59b7f9c56538d5c9ba949abac3c425083c1334947bc0572235dea1ed0b92
+  data.tar.gz: 64bde79e3880ac363fc31e0d37dcae5e4e3657ec4f55807385378e3f59699fb211204a1fdf8339d4e8dc9e5d4ce8dad1bb71e82d5c6b845c1697dbc136cc99ba

data/.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+quote_type = single

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,39 @@
+<!-- markdownlint-disable MD013 -->
+## Scope
+
+<!--
+Which roadmap milestone or issue does this PR implement?
+Link the relevant `docs/v1/*.md` line or the GitHub issue.
+-->
+
+## What this PR ships
+
+<!--
+Bullet list of the public-facing changes.
+-->
+
+-
+
+## Verification
+
+<!--
+Paste the tail of the local pipeline (or just confirm rake ci is green).
+
+```sh
+bundle exec rake ci
+```
+-->
+
+## Out of scope
+
+<!--
+Anything that was deliberately left for a follow-up PR.
+-->
+
+## Checklist
+
+- [ ] `CHANGELOG.md` entry added under `[Unreleased]`.
+- [ ] Tests added or updated under `test/`.
+- [ ] Docs updated under `docs/` (and the relevant `docs/v1/*.md` checkbox
+      flipped if a roadmap item is closing).
+- [ ] `bundle exec rake ci` is green locally.

data/.github/dependabot.yml

@@ -9,3 +9,7 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/ci.yml

@@ -0,0 +1,140 @@
+---
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Default to least privilege; jobs may opt into more.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Minitest (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.4', '4.0']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake test
+
+  rubocop:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+      - name: Run RuboCop
+        run: bundle exec rubocop --parallel
+
+  steep:
+    name: Steep
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - name: Run Steep
+        run: bundle exec steep check --jobs=1
+
+  coverage:
+    name: Coverage (SimpleCov)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+      - name: Run tests with SimpleCov
+        run: bundle exec rake test
+      - name: Append coverage summary
+        if: always()
+        run: |
+          ruby -rjson -e '
+            path = "coverage/.last_run.json"
+            unless File.exist?(path)
+              warn "no coverage/.last_run.json produced"
+              exit 0
+            end
+            data = JSON.parse(File.read(path))
+            line = data.dig("result", "line")
+            branch = data.dig("result", "branch")
+            File.open(ENV.fetch("GITHUB_STEP_SUMMARY"), "a") do |f|
+              f.puts "## SimpleCov coverage"
+              f.puts
+              f.puts "| Metric | Coverage | Soft target |"
+              f.puts "| ------ | -------- | ----------- |"
+              f.puts "| Line   | #{line}% | >= 98% |"
+              f.puts "| Branch | #{branch}% | >= 95% |"
+              f.puts
+              f.puts "Reported only; not enforced in CI. See docs/v1/05-quality-and-tooling.md."
+            end
+          '
+      - name: Upload coverage HTML artifact
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-html
+          path: coverage/
+          if-no-files-found: warn
+
+  runtime-deps:
+    name: Runtime deps assertion (zero)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+      - name: Assert assistant.gemspec declares zero runtime dependencies
+        run: |
+          ruby -e '
+            spec = Gem::Specification.load("assistant.gemspec")
+            deps = spec.runtime_dependencies.map(&:name)
+            if deps.empty?
+              puts "OK: assistant has zero runtime dependencies."
+            else
+              warn "FAIL: unexpected runtime dependencies: #{deps.join(", ")}"
+              exit 1
+            end
+          '
+
+  bin-smoke:
+    name: bin/ scripts smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          # Intentionally no bundler-cache: bin/setup is the thing under
+          # test; we want it to drive the bundle install end-to-end on a
+          # cold checkout.
+      - name: bin/setup smoke (cold bundle install)
+        run: ./bin/setup
+      - name: Syntax check bin/ scripts
+        run: |
+          bash -n bin/setup
+          ruby -c bin/console
+          ruby -c bin/version
+      - name: bin/version --help smoke
+        run: bundle exec bin/version --help
+      - name: bin/console loads assistant
+        run: |
+          echo 'puts Assistant::VERSION; exit' | bundle exec bin/console

data/.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+---
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - _config.yml
+      - Gemfile
+      - Gemfile.lock
+      - .github/workflows/docs.yml
+  pull_request:
+    branches: [main]
+    paths:
+      - docs/**
+      - _config.yml
+      - Gemfile
+      - Gemfile.lock
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: jekyll build --strict_front_matter
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_WITH: docs
+      JEKYLL_ENV: production
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - name: Build site
+        run: bundle exec jekyll build --strict_front_matter --baseurl "/assistant"
+      - name: Upload site artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+---
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+
+# Default to least privilege; the release job opts into the perms it needs.
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Build and publish gem
+    runs-on: ubuntu-latest
+    environment: rubygems
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+
+      - name: Run tests before publishing
+        run: bundle exec rake test
+
+      - name: Configure trusted publishing
+        uses: rubygems/configure-rubygems-credentials@v2.1.0
+
+      - name: Build gem
+        run: gem build assistant.gemspec
+
+      - name: Push gem to RubyGems
+        run: gem push assistant-*.gem
+
+      - name: Create GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: assistant-*.gem

data/.gitignore

@@ -4,10 +4,14 @@
 /coverage/
 /doc/
 /pkg/
+/_site/
+/.jekyll-cache/
+/.jekyll-metadata
 /spec/reports/
 /tmp/
 
 # rspec failure tracking
 .rspec_status
 .byebug_history
-assistant-*.gem
+assistant-*.gem
+.vscode/

data/.markdownlint.json

@@ -0,0 +1,6 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD024": { "siblings_only": true },
+  "MD043": false
+}

data/.opencode/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+package.json
+package-lock.json
+bun.lock

data/.opencode/opencode.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "@tarquinen/opencode-dcp@latest",
+    [
+      "@plannotator/opencode@latest",
+      {
+        "workflow": "plan-agent",
+        "planningAgents": ["plan"]
+      }
+    ]
+  ]
+}

data/.opencode/skills/create-pr/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: create-pr
+description: Use when opening a GitHub pull request for the assistant gem (e.g. `gh pr create`, "open a PR", "ship this branch"). Ensures local checks pass, only intended files are committed, commit/PR follow the M<num> convention, and the PR is assigned to the GitHub user before returning the URL.
+---
+
+# Skill: create-pr
+
+PRs for this repo follow a strict shape. Walk through every step in order.
+Skipping any one of them is a defect.
+
+## 1. Verify local checks before pushing
+
+Run all three from the worktree root and confirm each is green. None of these
+should be skipped because "the change is small" — the CI gate will reject the
+PR anyway.
+
+```sh
+bundle exec rake test
+bundle exec rubocop
+bundle exec steep check --jobs=1
+```
+
+If anything fails, fix it on the branch (or revert the offending hunk) before
+committing. Do not commit "WIP" or "fix in CI" placeholders.
+
+## 2. Stage only the intended files
+
+Inspect `git status --short` before staging. Explicitly enumerate paths to
+`git add` — never run `git add .` or `git add -A`.
+
+**Always exclude** the following even if they appear as untracked or modified:
+
+- Anything under `.opencode/` **except** committed config (`.opencode/.gitignore`,
+  `.opencode/opencode.json`) and project-owned skills under
+  `.opencode/skills/<name>/`. Transient agent state, scratch files, and
+  unrelated skills (e.g. `.opencode/skills/ruby-services/` if not owned by
+  this project) stay untracked.
+- `.DS_Store`, `*.swp`, `*~`, any local-only debug scripts
+- `Gemfile.lock` is fine to commit when an actual dep changed; do not stage it
+  for unrelated mechanical updates
+
+If something unrelated was modified during exploration (e.g. accidental
+reformat of an untouched file), restore it with `git restore <path>` first.
+
+After staging, re-check with `git diff --cached --stat` and confirm the file
+list matches the PR's scope.
+
+## 3. Commit message convention
+
+The repo's commit messages follow:
+
+```
+<TAG>: <short imperative summary, <=72 chars>
+
+<wrapped body explaining the WHAT and WHY, not the HOW>
+<reference roadmap milestones or issues by ID>
+```
+
+`<TAG>` is one of:
+
+- `M<n>` — a v1 roadmap milestone (e.g. `M11: bin/assistant-rbs per-class
+  RBS generator`). Look up the number in `docs/v1/02-features.md`.
+- `M-S<n>` — a "stretch" / promoted roadmap item.
+- `D<n>` — a documentation milestone from `docs/v1/04-documentation.md`.
+- A short topic tag like `chore:`, `docs:`, `refactor:` when the change does
+  not map to a roadmap item.
+
+The body wraps at ~72 cols and explains the WHY. Do not paste tool output or
+file lists — the diff already shows that.
+
+Pre-commit hooks may reject the commit. If they do, fix the issue and create
+a **new** commit. Do not `--amend` past hook failures.
+
+## 4. Push and track
+
+```sh
+git push -u origin <branch>
+```
+
+The branch name should already match the work: `feature/m<n>-<slug>` for
+roadmap milestones, or `<topic>/<slug>` otherwise.
+
+## 5. Open the PR
+
+Use `gh pr create` with `--base main`, the explicit `--head <branch>`, a
+`--title` that mirrors the lead commit's subject, and a `--body` that covers:
+
+- **Scope** — what milestone / issue this implements (link the roadmap line).
+- **What this PR ships** — bullet list of the public-facing changes.
+- **Sample output / behavior** — fenced block when the change has a visible
+  surface (CLI output, generated artifact, error message).
+- **Verification** — the green output of `rake test`, `rubocop`, and
+  `steep check`. Paste the actual tail of each command.
+- **Out of scope** — what was deliberately left for later (e.g. "M12 changes
+  this DSL signature; that ships in its own PR").
+
+Pass the body via a heredoc so newlines and quoting survive:
+
+```sh
+gh pr create --base main --head <branch> --title "..." --body "$(cat <<'EOF'
+...
+EOF
+)"
+```
+
+## 6. Assign the PR
+
+GitHub does not auto-assign. **Always** assign the PR to the authenticated
+user immediately after creation:
+
+```sh
+gh pr edit <number> --add-assignee "$(gh api user --jq .login)"
+```
+
+Confirm the assignment landed by re-reading the PR URL output — `gh pr edit`
+prints the URL on success.
+
+## 7. Return the PR URL
+
+The final message to the user must include the PR URL on its own line so the
+terminal renders it as a clickable link. Mention the PR number, the commit
+SHA(s) it contains, and the assignee.
+
+## Common pitfalls
+
+- **Committing transient `.opencode/` state** — agent scratch files and skills
+  that aren't owned by this repo must never appear in `git status` as staged.
+  Project-owned skills under `.opencode/skills/<name>/SKILL.md` are fine to
+  commit when they're part of the change.
+- **Forgetting to push before `gh pr create`** — `gh` will error with
+  `pull request create failed: GraphQL: No commits between main and …`.
+  Always `git push -u origin <branch>` first.
+- **Skipping the assignee step** — unassigned PRs get lost in the review
+  queue. Always run step 6.
+- **Empty `--body`** — `gh pr create` will silently use the commit message as
+  the body, which usually under-documents the change. Always pass `--body`.
+- **`--amend` after a pre-commit hook failure** — the failure already left
+  artifacts in the index; create a fresh commit instead.

data/.opencode/skills/ruby-services/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ruby-services
+description: Use when creating, changing, testing, or reviewing Ruby service objects, especially Assistant::Service subclasses, service inputs, validation, execution, logs, or Minitest coverage.
+---
+
+# Ruby Services
+
+Use this skill when working on Ruby service objects in this repository,
+especially `Assistant::Service` subclasses or framework behavior that affects
+service inputs, validation, execution, logs, result hashes, or tests.
+
+Do not use this skill for unrelated Ruby scripts, packaging-only changes, or
+opencode configuration tasks unless the work directly concerns Ruby service
+guidance.
+
+## Core Approach
+
+- Preserve the existing `Assistant::Service` public API unless the user asks for
+  an API change.
+- Prefer soft-fail service behavior: report domain and validation failures with
+  error logs instead of raising, unless an exception is explicitly part of the
+  API being changed.
+- Keep service logic clear and object-oriented: every method should have one
+  responsibility.
+- Only add a private helper when it makes sense in the context of the service's
+  domain and improves readability.
+- Keep helper names aligned with what the service does, not generic process
+  steps like `handle_data` or `process_stuff`.
+- Do not add arguments to service instance methods other than `initialize`.
+  Service behavior should use declared inputs and instance state.
+- Return computed data from `execute`; put pre-execution domain checks in
+  `validate`.
+- Use `log_item_warning`, `log_item_error`, `log_item_info`, or
+  `add_log(level:, source:, detail:, message:)` consistently with existing
+  log patterns.
+
+## Inputs
+
+- Declare service inputs with `input :name, type: SomeClass` and existing DSL
+  options such as `required:`, `optional:`, `default:`, `allow_nil:`, and `if:`.
+- Prefer `default: -> { [] }` or `default: -> { {} }` for mutable defaults.
+- Use `allow_nil: true` only when explicit `nil` is a valid service value.
+- Do not depend on deprecated `valid_require_*?` names in new internal code;
+  use the canonical `valid_required_*?` names.
+
+## Tests
+
+- Add or update Minitest coverage under `test/**/*_test.rb` for behavior
+  changes.
+- Use anonymous `Class.new(Assistant::Service)` fixtures for framework-level
+  service behavior, matching the existing tests.
+- Assert the service result hash shape, `status`, `warnings`, `errors`, logs,
+  and memoization when relevant.
+- For input DSL changes, cover required, optional, default, type, conditional,
+  and `allow_nil` behavior as applicable.
+- Use helpers from `test/test_helper.rb` for log-item construction or warning
+  capture instead of duplicating helper setup.
+
+## Style
+
+- Ruby target is 3.4.
+- Start Ruby files with `# frozen_string_literal: true`.
+- Prefer concise Ruby that matches nearby code; endless methods are acceptable
+  where they are already used.
+- Respect the repo's hybrid compact nesting convention from
+  `rubocop-style-compact_nesting`.
+- Keep public API documentation aligned with `docs/v1/01-api-surface.md` and
+  user-facing changes aligned with `CHANGELOG.md` when appropriate.
+- Make the smallest correct change; avoid generic abstractions until there is a
+  concrete second use.
+
+## Verification
+
+Run the focused test first when possible, then the broader checks relevant to
+the change:
+
+```sh
+bundle exec ruby -Itest test/assistant/service_test.rb
+bundle exec rake test
+bundle exec rubocop
+```