socketry 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70633286c7d535c7a1acac275bb9e5e5878e27afcd25b5e8bf2ab03964276c63
-  data.tar.gz: c1487b99904ba7ae5124a00e2a962a598e16990f964b8fd81eb0dd24c6981730
+  metadata.gz: adc302f7cd0dc7a5eb75de8681bd2f9bee242a4a8186bbc5f6d5ba4bebbbbd8d
+  data.tar.gz: cf7111e7a3b30fe26047b96143a79ec4a07d687ea5ae60e316cee986679f470f
 SHA512:
-  metadata.gz: 00603f0c6a8087a501603077a624b42bf7889e121a59f82d04d680f1befefaea18f467869d21eaedb668853dc46c7f61ce40d3e695c0210ce0b9603651a75446
-  data.tar.gz: aca0f634e62a86336a66eb4005ebc80e09e07d5b3a687455bfacbba556bd0572341f7743cd401db4632ef09eedee695b12c2a0943f254a191e289be61a899a56
+  metadata.gz: bc5813a0093c10da9fae1c8a4a2546a577359fd871239a73e828e1d58468462a5cb7fd0a60946eefe069fa143003759668bbe46420596562b1f43af954f2d7c7
+  data.tar.gz: e1deae7929c4a53fd1210ad80d88df165a3aef1387977f6f996ac9cac63e768023449af50f61f02b1ba5f5aac4a8ed7f47105415bf8adc7a9ee238767a5f5488

data/context/getting-started.md

@@ -0,0 +1,74 @@
+# Getting Started
+
+This guide explains how to use the `socketry` gem to support Socketry development by installing shared guidance and agent skills into your local project.
+
+## Purpose
+
+The `socketry` gem distributes conventions, design patterns, and reusable agent skills for developing and maintaining Socketry projects. It gives contributors and coding agents a common set of instructions for work such as implementing configuration DSLs, preparing pull requests, and maintaining GitHub repositories.
+
+The guides are packaged as agent context, while task-specific instructions are packaged as skills. Use [`agent-context`](https://github.com/socketry/agent-context) and [`agent-skills`](https://github.com/socketry/agent-skills) to install them from the gem into your project.
+
+## Installation
+
+Add these gems to the maintenance group in your project's `gems.rb` or `Gemfile`:
+
+```ruby
+group :maintenance, optional: true do
+	gem "socketry"
+	gem "agent-context"
+	gem "agent-skills"
+end
+```
+
+Enable the group and install the gems from the project root:
+
+```bash
+bundle config set --local with maintenance
+bundle install
+```
+
+## Install Agent Context
+
+Install Socketry's guides locally:
+
+```bash
+bundle exec bake agent:context:install --gem socketry
+```
+
+This copies the guides into `.context/socketry/` and updates the context index in your project's `agents.md`. Agents can follow those links to read conventions such as [Pattern: Configuration & Builder](https://socketry.github.io/socketry/guides/pattern-configuration-and-builder/index).
+
+To inspect the available context files:
+
+```bash
+bundle exec bake agent:context:list --gem socketry
+```
+
+## Install Agent Skills
+
+Install Socketry's reusable workflows locally:
+
+```bash
+bundle exec bake agent:skills:install --gem socketry
+```
+
+This copies the skills into `.agents/skills/`, including `socketry-pull-request` and `socketry-github-repository`. Each skill has a `SKILL.md` describing when to use it and the instructions to follow.
+
+To inspect the available skills:
+
+```bash
+bundle exec bake agent:skills:list --gem socketry
+```
+
+Omit `--gem socketry` from either installer to install the context or skills provided by all dependencies in the bundle.
+
+## Update Local Guidance
+
+After updating the gem, rerun both installers to refresh the local copies:
+
+```bash
+bundle update socketry
+bundle exec bake agent:context:install --gem socketry
+bundle exec bake agent:skills:install --gem socketry
+```
+
+Make changes to Socketry's guides and skills in this repository; installed copies are replaced when refreshed. The generated `.context/` and `.agents/` directories can be ignored in version control and recreated during local setup.

data/context/index.yaml

@@ -0,0 +1,25 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Socketry project metadata, agent context, and skills.
+metadata:
+  bug_tracker_uri: https://github.com/socketry/socketry/issues
+  changelog_uri: https://github.com/socketry/socketry/blob/main/releases.md
+  documentation_uri: https://socketry.github.io/socketry/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/socketry.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use the `socketry` gem to support Socketry
+    development by installing shared guidance and agent skills into your local project.
+- path: pattern-gem-structure.md
+  title: 'Pattern: Gem Structure'
+  description: This guide explains how to organise a Socketry gem, including its dependencies,
+    library code, tests, configuration, documentation, and files maintained by `bake
+    modernize`.
+- path: pattern-configuration-and-builder.md
+  title: 'Pattern: Configuration & Builder'
+  description: This guide explains how to implement Ruby configuration DSLs with a
+    mutable `Configuration` and a separate `Builder`, including file loading and explicit
+    freezing.

data/context/{configuration.md → pattern-configuration-and-builder.md}

@@ -1,6 +1,6 @@
-# Configuration and Builder
+# Pattern: Configuration & Builder
 
-Use a mutable `Configuration` and a separate `Builder` for Ruby configuration DSLs in Socketry projects. This guide defines their responsibilities, construction, file loading, and explicit freezing.
+This guide explains how to implement Ruby configuration DSLs with a mutable `Configuration` and a separate `Builder`, including file loading and explicit freezing.
 
 ## Design
 
@@ -148,7 +148,3 @@ Multiple top-level files share one configuration. The example applies them in or
 Use this design for new configuration DSLs and when standardising existing ones. Preserve existing public names and entry points as compatibility wrappers where needed; an existing `Loader` can retain its name while the implementation moves to `Builder`. Keep runtime query methods and domain validation on the configuration.
 
 Verify that block and file factories return the configured object, that it can still be changed through the direct API, and that builders for multiple files update that same object. Explicit freezing should return that object, tolerate repeated calls, and prevent changes to its owned state through writers, collection readers, or attached builders, while leaving application objects untouched. For nested files, check relative resolution, stable builder roots, and exception source locations.
-
-## Established Examples
-
-This design follows [Falcon's configuration/loader separation from June 2019](https://github.com/socketry/falcon/commit/438e04eb295400f0481d72b610a2f9c9ea062746), carried into [Async::Service in February 2024](https://github.com/socketry/async-service/commit/d2d717b7605d364df3a853e8a810aeab2bc36078). Async::Service's [configuration](https://github.com/socketry/async-service/blob/f32af00e5c7a54c936023b96f180710e811d410e/lib/async/service/configuration.rb) and [loader](https://github.com/socketry/async-service/blob/f32af00e5c7a54c936023b96f180710e811d410e/lib/async/service/loader.rb) illustrate the mutable state and per-file loading scopes. This standard uses the name `Builder` for that DSL role.

data/context/pattern-gem-structure.md

@@ -0,0 +1,258 @@
+# Pattern: Gem Structure
+
+This guide explains how to organise a Socketry gem, including its dependencies, library code, tests, configuration, documentation, and files maintained by `bake modernize`.
+
+## Layout
+
+A consistent layout helps contributors find the implementation, test a change, and understand what will be shipped to users. Use this structure when creating a gem or bringing an existing project into line with Socketry conventions.
+
+The examples use a gem named `example` with the namespace `Example`. Substitute the project's own name, metadata, and supported Ruby versions. Create additional directories as the project needs them.
+
+```text
+example/
+├── example.gemspec
+├── gems.rb
+├── lib/
+│   ├── example.rb
+│   └── example/
+│       └── version.rb
+├── test/
+│   ├── example.rb
+│   └── example/
+├── config/
+│   └── sus.rb
+├── guides/
+│   ├── links.yaml
+│   └── getting-started/
+│       └── readme.md
+├── context/
+│   ├── index.yaml
+│   └── getting-started.md
+├── bake.rb
+├── readme.md
+├── releases.md
+├── license.md
+├── .editorconfig
+├── .gitignore
+├── .rubocop.yml
+└── .github/
+    ├── copilot-instructions.md
+    └── workflows/
+```
+
+## Gemspec
+
+The root `example.gemspec` defines the package installed by users: its name, version, metadata, supported Ruby versions, runtime dependencies, and packaged files. It reads the version from the library's version file:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "lib/example/version"
+
+Gem::Specification.new do |spec|
+	spec.name = "example"
+	spec.version = Example::VERSION
+	spec.summary = "An example Socketry library."
+	spec.authors = ["Your Name"]
+	spec.license = "MIT"
+	spec.homepage = "https://github.com/your-org/example"
+	
+	spec.metadata = {
+		"documentation_uri" => "https://your-org.github.io/example/",
+		"source_code_uri" => "https://github.com/your-org/example.git",
+		"changelog_uri" => "https://github.com/your-org/example/blob/main/releases.md",
+	}
+	
+	spec.files = Dir.glob(["{context,lib}/**/*", "*.md"], File::FNM_DOTMATCH, base: __dir__)
+	spec.required_ruby_version = ">= 3.3"
+end
+```
+
+Loading just the version file allows Bundler and RubyGems to evaluate the gemspec before the library's dependencies are installed. Keep that file independent of the rest of the library.
+
+Declare dependencies needed by the library with `spec.add_dependency`, including appropriate version requirements. Development tools belong in `gems.rb`.
+
+Maintain `spec.files` as the list of files users need. Include `context/` when distributing agent context, `skills/` when providing agent skills, `bake/` when exporting Bake tasks, and `bin/` or `ext/` when the gem provides executables or native extensions. Executables also need `spec.executables`; native extensions need `spec.extensions`. Keep local bundles, generated sites, test output, and other working files out of the package. See the [RubyGems specification reference](https://guides.rubygems.org/specification-reference/) for these fields.
+
+## `gems.rb`
+
+`gems.rb` is the Bundler manifest for working on the project. The `gemspec` directive includes the local gem and its runtime dependencies. Follow the layout used by `bake-modernize`: put the optional maintenance group before the test group, and separate related sets of tools with blank lines:
+
+```ruby
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :maintenance, optional: true do
+	gem "bake-modernize"
+	gem "bake-gem-github"
+	gem "bake-releases"
+	
+	gem "socketry"
+	gem "agent-context"
+	gem "agent-skills"
+	
+	gem "decode"
+	
+	gem "utopia-project"
+end
+
+group :test do
+	gem "sus"
+	gem "covered"
+	
+	gem "rubocop"
+	gem "rubocop-md"
+	gem "rubocop-socketry"
+	
+	gem "bake-test"
+end
+```
+
+Enable maintenance tools locally when needed:
+
+```bash
+bundle config set --local with maintenance
+bundle install
+```
+
+Bundler writes the resolved dependencies to `gems.locked`. The standard `bake modernize` ignore rules leave this lockfile untracked for gem development. Runtime compatibility is expressed in the gemspec's dependency requirements; the local lockfile records the versions used in that checkout.
+
+`bake modernize:gemfile` renames `Gemfile` to `gems.rb` and `Gemfile.lock` to `gems.locked`. Maintain one manifest. The [Getting Started guide](https://socketry.github.io/socketry/guides/getting-started/index) explains how to install the shared Socketry context and skills after installing these tools.
+
+## Library Code and Version
+
+Put library code under `lib/`, following the Ruby namespace. For example, `async-service` uses `lib/async/service.rb`, `lib/async/service/`, and the namespace `Async::Service`. Keep each file's required dependencies explicit so supported entry points can be loaded directly.
+
+Define the version once in `lib/example/version.rb`. Start a new gem at `0.0.0` so the first version bump reflects the initial implementation:
+
+```ruby
+# frozen_string_literal: true
+
+# @namespace
+module Example
+	VERSION = "0.0.0"
+end
+```
+
+The public entry point, `lib/example.rb`, loads the version and the public components needed by callers:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "example/version"
+```
+
+As the library grows, add its implementation files under `lib/example/` and require the appropriate files from the entry point. Consumers load the library with `require "example"`. The gemspec and callers both use the same `Example::VERSION` constant.
+
+## Tests and Configuration
+
+Place Sus tests under `test/`, mirroring the library paths. For example, tests for `lib/example/connection.rb` belong in `test/example/connection.rb`. Shared test data and contexts can live in `fixtures/`, which Sus adds to the load path.
+
+A small `test/example.rb` checks that the public entry point loads and exposes a version:
+
+```ruby
+# frozen_string_literal: true
+
+require "example"
+
+describe Example do
+	it "has a version number" do
+		expect(Example::VERSION).to be =~ /\A\d+\.\d+\.\d+\z/
+	end
+end
+```
+
+Add tests for the library's behaviour alongside this initial check.
+
+Use `config/` for project tooling configuration. `config/sus.rb` is loaded by Sus and can enable coverage:
+
+```ruby
+# frozen_string_literal: true
+
+require "covered/sus"
+include Covered::Sus
+```
+
+Other tools use their own files here when needed: `config/external.yaml` selects downstream projects for `bake-test-external`, and `config/release.yaml` records the GitHub release policy for `bake-gem-github`. These files configure development and maintenance workflows; the library's configuration API belongs with its code under `lib/`.
+
+Run the suite and style checks from the project root:
+
+```bash
+bundle exec sus
+bundle exec rubocop
+```
+
+`bundle exec bake test` runs the project's tests through `bake-test`, as used by the standard CI workflows.
+
+## README and Guides
+
+`readme.md` introduces the project with a short description, its purpose, and a path to useful documentation. Include usage, contributing, test, and release instructions. Socketry uses lowercase names for root Markdown files; `bake modernize` normalises these names and updates standard README sections and the test badge.
+
+Write detailed documentation in `guides/<guide-name>/readme.md`, with ordering in `guides/links.yaml`. Set `documentation_uri` in the gemspec to the documentation site's base URL, including its trailing slash, so generated links resolve correctly.
+
+Regenerate documentation metadata after editing guides:
+
+```bash
+bundle exec bake utopia:project:update
+```
+
+This updates the README's existing `Usage` and `Releases` sections and exports the guides into `context/` with an `index.yaml`. Commit those generated context files so the gem can distribute them. The `.context/` directory contains guidance installed from dependencies for local use.
+
+Keep release notes in `releases.md`, adding changes under `## Unreleased`. `license.md` records the project's license and copyright information.
+
+## Bake Tasks and Releases
+
+`bake.rb` contains tasks and hooks for maintaining this project. For a gem using `bake-modernize`, `bake-releases`, and `utopia-project`, the version-bump hook refreshes copyrights before updating release notes and generated documentation:
+
+```ruby
+# frozen_string_literal: true
+
+def after_gem_release_version_increment(version)
+	context["modernize:license"].call
+	context["releases:update"].call(version)
+	context["utopia:project:update"].call
+end
+```
+
+`modernize:license` updates `license.md` and Ruby copyright headers from Git history. `bake-modernize` 0.62.0 and later include this call in the generated hook for both `bake-gem` and `bake-gem-github`. Existing projects can update `bake-modernize`, run `bundle exec bake modernize:releases`, and review the merged `bake.rb` to pick up the new call while preserving custom hooks.
+
+Tasks intended for other projects belong in namespaced files under `bake/` and must be included in `spec.files`. For example, `bake/example.rb` can provide `example:setup`. The root `bake.rb` is specific to the gem's own checkout.
+
+Projects using `bake-gem-github` also have `config/release.yaml`, `.github/release-rules/`, and release preparation, validation, and publishing workflows. Its setup tasks generate those files separately from the default modernization. Follow the [bake-gem-github setup guide](https://socketry.github.io/bake-gem-github/guides/getting-started/index) to configure publishing and apply the GitHub rules.
+
+## Files Maintained by `bake modernize`
+
+`bake modernize` updates an existing gem's conventions. Start with the gemspec, version file, library entry point, and tests described above. Its tasks maintain these supporting files:
+
+| File | Purpose |
+| --- | --- |
+| `.editorconfig` | Shared editor settings, including indentation and line endings. |
+| `.gitignore` | Excludes local Bundler state, `gems.locked`, packaged gems, coverage data, installed skills, and other generated working files. |
+| `.rubocop.yml` | Ruby and Markdown code style using `rubocop-socketry` and `rubocop-md`. |
+| `.github/workflows/test.yaml` | Runs tests across the supported Ruby matrix. |
+| `.github/workflows/rubocop.yaml` | Checks code style. |
+| `.github/workflows/test-coverage.yaml` | Measures test coverage. |
+| `.github/workflows/documentation-coverage.yaml` | Checks source documentation coverage with Decode. |
+| `.github/workflows/documentation.yaml` | Builds and publishes the Utopia documentation site. |
+| `.github/workflows/test-external.yaml` | Runs downstream tests when `config/external.yaml` exists. |
+| `.github/copilot-instructions.md` | Provides repository instructions for GitHub Copilot. |
+| `license.md` and source headers | Maintain licensing and contributor copyright information. |
+| `releases.md`, `bake.rb`, and `readme.md` | Maintain release notes, release hooks, and contributor instructions. |
+| `release.cert` | Public gem-signing certificate, copied when `~/.gem/release.cert` exists. The matching private key stays outside the repository. |
+
+Modernization also rewrites the gemspec and updates tool dependencies. Review changes to the supported Ruby version, packaged files, dependency requirements, and existing customisations.
+
+From a clean checkout with maintenance dependencies installed, list the tasks and review the generated changes:
+
+```bash
+bundle exec bake list modernize
+bundle exec bake modernize
+git diff
+```
+
+Some tasks install dependencies, inspect GitHub metadata, or merge existing files using a local Ollama service. Consult the [bake-modernize guide](https://socketry.github.io/bake-modernize/guides/getting-started/index) for setup and individual tasks. Run the project's tests and review the diff before committing.
+
+GitHub releases are an explicit opt-in through `bake modernize:releases:github` and the subsequent `bake-gem-github` setup. When that dependency is already present, modernization maintains the corresponding release hooks and README instructions.

data/lib/socketry/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Socketry
-	VERSION = "0.6.1"
+	VERSION = "0.6.2"
 end

data/readme.md

@@ -4,11 +4,19 @@ Socketry project metadata, agent context, and skills.
 
 [![Development Status](https://github.com/socketry/socketry/workflows/Test/badge.svg)](https://github.com/socketry/socketry/actions?workflow=Test)
 
-## Agent Context
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/socketry/) for more details.
 
-This gem distributes project conventions in the top-level `context/` directory:
+  - [Getting Started](https://socketry.github.io/socketry/guides/getting-started/index) - This guide explains how to use the `socketry` gem to support Socketry development by installing shared guidance and agent skills into your local project.
 
-  - [Configuration and Builder](context/configuration.md) defines the mutable configuration and builder design for Ruby configuration DSLs.
+  - [Pattern: Gem Structure](https://socketry.github.io/socketry/guides/pattern-gem-structure/index) - This guide explains how to organise a Socketry gem, including its dependencies, library code, tests, configuration, documentation, and files maintained by `bake modernize`.
+
+  - [Pattern: Configuration & Builder](https://socketry.github.io/socketry/guides/pattern-configuration-and-builder/index) - This guide explains how to implement Ruby configuration DSLs with a mutable `Configuration` and a separate `Builder`, including file loading and explicit freezing.
+
+## Agent Context
+
+The guides are also distributed as agent context in the top-level `context/` directory.
 
 Projects that include `socketry` and [`agent-context`](https://github.com/socketry/agent-context) can install the context and update their `agents.md` index with:
 
@@ -22,7 +30,13 @@ This gem provides reusable agent skills in the top-level `skills/` directory. Us
 
 ## Releases
 
-Please see the [project releases](https://github.com/socketry/socketryreleases/index) for all releases.
+Please see the [project releases](https://socketry.github.io/socketry/releases/index) for all releases.
+
+### v0.6.2
+
+  - Document the standard Socketry gem layout and files maintained by `bake modernize` in "Pattern: Gem Structure".
+  - Add a Getting Started guide for installing Socketry's development context and agent skills locally.
+  - Publish "Pattern: Configuration & Builder" as a documentation guide and generate its agent context as `pattern-configuration-and-builder.md`.
 
 ### v0.6.1
 
@@ -47,6 +61,14 @@ To run the test suite:
 $ bundle exec sus
 ```
 
+### Updating Documentation
+
+Edit the source guides in `guides/`, then regenerate the README and distributed agent context:
+
+``` bash
+bundle exec bake utopia:project:update
+```
+
 ### Making Releases
 
 To make a new release:

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.6.2
+
+  - Document the standard Socketry gem layout and files maintained by `bake modernize` in "Pattern: Gem Structure".
+  - Add a Getting Started guide for installing Socketry's development context and agent skills locally.
+  - Publish "Pattern: Configuration & Builder" as a documentation guide and generate its agent context as `pattern-configuration-and-builder.md`.
+
 ## v0.6.1
 
   - Distribute the mutable Configuration and Builder convention through `agent-context`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: socketry
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Samuel Williams
@@ -13,7 +13,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- context/configuration.md
+- context/getting-started.md
+- context/index.yaml
+- context/pattern-configuration-and-builder.md
+- context/pattern-gem-structure.md
 - lib/socketry.rb
 - lib/socketry/version.rb
 - license.md
@@ -27,6 +30,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/socketry/socketry/issues
   changelog_uri: https://github.com/socketry/socketry/blob/main/releases.md
+  documentation_uri: https://socketry.github.io/socketry/
   funding_uri: https://github.com/sponsors/ioquatix/
   source_code_uri: https://github.com/socketry/socketry.git
 rdoc_options: []