prompt_manager 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2de9f9b60b1bad9884fba07f280c00316c05dbd8d5f6b86e01805e461aaf968
-  data.tar.gz: 73162b249b9676d13bdf015a7cba72949d3fe9834ff6b6441fbe452048613e04
+  metadata.gz: 19379206907c5abb7a46bc56a035d93ab2ccc384de6ce516080604019aecaf9d
+  data.tar.gz: c5a88a56de993fe7ff0e65ccd5a7d07572a3696ddca2b2787b63e8ff460c1a6f
 SHA512:
-  metadata.gz: eb50e40c8eeb0873a68b1d84481391a1fa7b0c8f1971a461b662b86faa101bd3fd58a584f4364f2510e9df282904e3329f64b6319a16a684020b574f3aa0f1a1
-  data.tar.gz: 20f9e743881dca244716a5e14e97a34a050e07afb6ac954122988acf0cd7fd3b9bdf20c726ab73885c1a10301cc5ccdd194bcc38c50611340b6f77c06e87d2ab
+  metadata.gz: dba13493af0167fd8f9a5f75ee5259b2731ad3fd849fd6ec3427fdf25389c2a9e51b888280238069e231e2a4e7aaf84ba93bbc6eaf87e38667fa41a67ce86285
+  data.tar.gz: 405110550b15a0d180aa76ef537a76169a042d373dc94f3fc8c19f9dfd4beedff86fec1dcd97abcea446d12ba5ff233673606989863e893928083e84b49f21c2

data/CHANGELOG.md

@@ -1,28 +1,139 @@
-### [1.0.2] - 2026-02-09
-
-#### Changed
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [1.2.0] - 2026-11-01
+
+### Fixed
+
+- **Parameters named after private Kernel methods.** A parameter called
+  `format`, `test`, `system` or another private `Kernel` method rendered the
+  method instead of the value (`<%= format %>` raised `ArgumentError`).
+  Parameters now shadow private as well as public `Object` methods. Called
+  with arguments or a block (`format('%d', 1)`), the name is still the
+  method. `binding` is never shadowed.
+
+## [1.1.0] - 2026-11-01
+
+A hardening release. Shell expansion can no longer be hijacked by its own
+output, the include chain works as documented, every failure PM raises has a
+class of its own, and the gem ships with zero runtime dependencies at 23 KB
+instead of 9.6 MB. No template syntax changed; see **Upgrading** for the
+behaviour that did.
+
+### Upgrading from 1.0.x
+
+- **Ruby 4.0.9 or later is required** (was 3.2).
+- **Errors are typed.** Failures that raised `RuntimeError` now raise a
+  `PM::Error` subclass (`PM::CircularIncludeError`, `PM::ShellCommandError`,
+  `PM::FileNotFoundError`, ...). `rescue RuntimeError` no longer catches them;
+  `rescue PM::Error` does. Missing-parameter errors are still `ArgumentError`s
+  with the same message, via `PM::MissingParameterError`.
+- **Two silent cases now raise:** an unmatched `$(` (`PM::ShellExpansionError`)
+  and a `shell:` / `erb:` value that is not a boolean or true/false/yes/no/on/off
+  (`PM::MetadataError`).
+- **`PM::Metadata` is no longer an `OpenStruct`.** Dot access, predicates, `[]`,
+  `respond_to?`, and `to_h` are unchanged; only `is_a?(OpenStruct)` checks break.
+- **`PM::Parsed` and `PM::RenderContext` are immutable `Data` objects.** Readers
+  are unchanged; writers such as `parsed.content = ...` are gone.
+- **`PM.directives` returns a frozen snapshot.** Use `PM.register` and
+  `PM.reset_directives!` to change the registry.
+- **The gem no longer contains `docs/`, examples, or media.** Documentation is
+  at <https://madbomber.github.io/prompt_manager>.
+
+### Added
+
+- **Error hierarchy** rooted at `PM::Error`: `MetadataError`,
+  `ShellExpansionError` > `ShellCommandError` (`#command`, `#status`, `#stderr`),
+  `IncludeError` > `CircularIncludeError` / `IncludeDepthError` /
+  `IncludeContextError`, `FileNotFoundError`, `DirectiveAlreadyRegisteredError`;
+  plus `ParameterError` > `MissingParameterError` / `UnknownParameterError`
+  under `ArgumentError`.
+- **Configuration:** `lock!` / `unlock!` / `locked?` make the global `shell` and
+  `erb` final so a file cannot re-enable a stage; `max_include_depth` (default 10,
+  `nil` = unlimited); `strict_parameters` turns an unknown template name into
+  `PM::UnknownParameterError` instead of `""`. `PM.configure` returns the config.
+- **Shell expansion:** `\$` writes a literal `$`; fenced code blocks (``` / ~~~)
+  are skipped; `PM.expand_shell(str, erb_safe: true)` escapes `<%` in command output.
+- **`PM::Parsed`:** `#to_h`, `#to_markdown` (round-trippable front matter +
+  content, derived keys omitted), `#parameters`, `#key?`.
+- **`PM::Metadata`:** `Enumerable`, plus `dig`, `fetch`, `keys`, `values`,
+  `size`, `empty?`, `delete`, `each_pair`, `==`.
+- **`PM.directive?(name)`.**
+- **CI:** GitHub Actions on Ubuntu and macOS with a 100% line-coverage gate
+  (SimpleCov); `.ruby-version` pins development to 4.0.9.
+- **Docs:** new Security guide and Errors reference.
+
+### Changed
+
+- **Shell expansion is one left-to-right pass.** Command output is spliced in
+  verbatim and never re-scanned, so `$VAR`, `$(...)`, or `<%` printed by a
+  command stays text. Command stderr goes to `$stderr` on success and into
+  `ShellCommandError` on failure.
+- **`include` tracks ancestors, not every rendered file,** so the same fragment
+  can be included twice in one prompt. Included files may have any extension.
+- **Front matter is validated:** must be a mapping (or empty); `parameters:`
+  must be a mapping; flags are coerced as described under Upgrading.
+- **Directive registry policy:** `PM.register` is atomic (nothing is registered
+  if any name is taken). `PM::Directive.register_all` is idempotent, lets a later
+  subclass override an earlier one, and raises if a name was claimed with
+  `PM.register`.
+- **Template name resolution is defined:** parameter (called without arguments)
+  > directive > `nil` (or error in strict mode).
+- **Internals:** rendering moved from `Parsed` into `PM::Renderer` and
+  `PM::RenderScope`; `Parsed#render_with` remains for `include`.
+- **Packaging:** gemspec allow-lists `lib/**/*.rb`, `README.md`, `CHANGELOG.md`,
+  `LICENSE`; adds `changelog_uri`, `documentation_uri`, `bug_tracker_uri`;
+  development dependencies move to the Gemfile.
+
+### Fixed
+
+- Including the same file twice raised "Circular include detected".
+- Empty (`---\n---`) or scalar front matter raised `NoMethodError`.
+- `include` of a path without `.md` parsed the path string as the prompt.
+- `created_at` raised `NotImplementedError` on filesystems without birthtime;
+  it now falls back to `ctime`.
+- `erb: 'true'` (a string) silently disabled ERB.
+- A metadata key named like an `Object` method (`hash`, `method`, `display`)
+  returned the method instead of the value.
+- Two tests asserted nothing and produced `ruby -w` warnings; `.irbrc` used the
+  removed 0.x API.
+- Documentation corrections throughout: built-in directive lists, error messages,
+  `content` newline examples, `Struct` signatures, hard-coded version, an opening
+  example that registered the built-in `:read`, and fences nested inside fences.
+
+### Removed
+
+- The `ostruct` runtime dependency. PM now has none.
+- `test/pm_test.rb` (redundant with the Rakefile glob).
+- Documentation, examples, and media from the packaged gem.
+
+## [1.0.2] - 2026-02-09
+
+### Changed
 - Made `PM.parse_string` a public class method so it can be called directly for parsing strings without file-based metadata enrichment.
 
-### [1.0.1] - 2026-02-04
+## [1.0.1] - 2026-02-04
 
-#### Added
+### Added
 - **`PM::Directive` base class** — class-based DSL for defining directive categories. Use `desc` before method definitions to mark them as directives, and `alias_method` for aliases. Subclass tracking, `register_all`, `category_name`, and `build_dispatch_block` are all built-in.
 - **Built-in `insert` directive** (alias: `read`) — insert any file's raw content into a prompt. Unlike `include`, the inserted content is not parsed, shell-expanded, or ERB-rendered.
 - New test file `directive_base_test.rb` with tests for the `PM::Directive` DSL, subclass tracking, category naming, and dispatch block building.
 - New test fixtures for `insert`/`read` directive coverage.
 
-#### Changed
+### Changed
 - **`PM::CoreDirectives`** — built-in `include`, `insert`/`read` directives refactored as a `PM::Directive` subclass using the `desc` DSL.
 - `PM.register` directive aliases now support registration via `alias_method` in `PM::Directive` subclasses, with automatic detection via `UnboundMethod#original_name`.
 - Directive registry simplified; `PM.reset_directives!` now delegates to `PM::Directive.register_all`.
 - Updated README and documentation guides for custom directives and includes.
 
-## Released
-### [1.0.0] = 2026-02-03
+## [1.0.0] - 2026-02-03
 
 **Complete rewrite** — repositioned from a prompt management system with storage adapters to a focused prompt parsing and rendering engine.
 
-#### Breaking Changes
+### Breaking Changes
 - **New `PM` module replaces `PromptManager`** — the entire codebase has been restructured under the `PM` namespace. A backward-compatibility alias (`PromptManager = PM`) is provided via `require 'prompt_manager'`.
 - **Storage adapters removed** — `FileSystemAdapter`, `ActiveRecordAdapter`, and all database-backed persistence have been removed. The library now operates on strings, files, and Pathnames directly.
 - **`Prompt` class removed** — replaced by the lightweight `PM::Parsed` struct.
@@ -30,7 +141,7 @@
 - **Parameter history removed** — the library no longer tracks historical parameter values per keyword.
 - **Configuration simplified** — only three settings remain: `prompts_dir`, `shell`, and `erb`. Options like `parameter_regex` and `search_proc` have been removed.
 
-#### New Features
+### New Features
 - **Symbol and single-word parsing** — `PM.parse(:code_review)` and `PM.parse('code_review')` automatically resolve to `code_review.md` in the configured `prompts_dir`.
 - **Directive aliases** — `PM.register(:webpage, :website, :web) { |ctx, url| ... }` registers multiple names for a single directive with rollback on duplicate detection.
 - **`PM::Metadata`** — OpenStruct-based metadata with automatic predicate methods for boolean fields (e.g., `metadata.shell?`).
@@ -38,7 +149,7 @@
 - **Built-in `include` directive** — compose prompts from multiple files with loop protection.
 - **Streamlined parsing pipeline** — strip HTML comments, extract YAML front matter, optional shell expansion (`$VAR`, `${VAR}`, `$(command)`), optional ERB rendering.
 
-#### Removed
+### Removed
 - `PromptManager::Prompt` class
 - `PromptManager::DirectiveProcessor` class
 - `PromptManager::Storage::FileSystemAdapter`
@@ -46,35 +157,35 @@
 - Custom error classes (`PromptManager::Error` hierarchy)
 - Development dependencies on `activerecord`, `sqlite3`, and `tocer`
 
-#### Added
+### Added
 - Runtime dependency on `ostruct`
 - Comprehensive test suite (8 test files, 19 fixtures)
 - Full documentation site under `docs/` with guides for parsing, shell expansion, ERB rendering, custom directives, and prompt composition
 
-### [0.5.8] = 2025-09-01
+## [0.5.8] - 2025-09-01
 - fixed issue where removed keywords from prompt text were still being included in parameters if they existed in the JSON file (addresses AIA issue #105)
 - parameters now only include keywords currently present in the prompt text, while preserving historical values for existing keywords
 
-### [0.5.7] = 2025-06-25
+## [0.5.7] - 2025-06-25
 - fixed a problem when the value of a parameter is an empty array
 - fixed a failing test
 
-### [0.5.6] = 2025-06-04
+## [0.5.6] - 2025-06-04
 - fixed a problem where shell integration was not working correctly for $(shell command)
 
-### [0.5.5] = 2025-05-21
+## [0.5.5] - 2025-05-21
 - fixed bug in parameter substitution when value is an Array now uses last entry
 
-### [0.5.4] = 2025-05-18
+## [0.5.4] - 2025-05-18
 - fixed typo in the Prompt class envvar should have been envar which prevented shell integration from taking place.
 
-### [0.5.3] = 2025-05-14
+## [0.5.3] - 2025-05-14
 - fixed issue were directives were not getting their content added to the prompt text
 - Updated documentation and versioning.
 - Added new error classes for better error handling.
 - Improved parameter handling and directive processing.
 
-### [0.5.0] = 2025-03-29
+## [0.5.0] - 2025-03-29
 - Major refactoring of to improve processing of parameters and directives.
 - Added PromptManager::DirectiveProcessor as an example of how to implement custom directives.
 - Added support for //include directive that protects against loops.
@@ -82,33 +193,33 @@
 - Added support for ERB processing within a prompt.
 - Improved test coverage.
 
-### [0.4.2] = 2024-10-26
+## [0.4.2] - 2024-10-26
 - Added configurable parameter_regex to customize keyword pattern
 
-### [0.4.1] = 2023-12-29
+## [0.4.1] - 2023-12-29
 - Changed @directives from Hash to an Array
 - Fixed keywords not being substituted in directives
 
-### [0.4.0] = 2023-12-19
+## [0.4.0] - 2023-12-19
 - Add "//directives param(s)" with keywords just like the prompt text.
 
-### [0.3.3] = 2023-12-01
+## [0.3.3] - 2023-12-01
 - Added example of using the `search_proc` config parameter with the FileSystemAdapter.
 
-### [0.3.2] = 2023-12-01
+## [0.3.2] - 2023-12-01
 
 - The ActiveRecordAdapter is passing its unit tests
 - Dropped the concept of an sqlite3 adapter since active record can be used to access sqlite3 databases as well as the big boys.
 
-### [0.3.0] = 2023-11-28
+## [0.3.0] - 2023-11-28
 
 - **Breaking change** The value of the parameters Hash for a keyword is now an Array instead of a single value.  The last value in the Array is always the most recent value used for the given keyword.  This was done to support the use of a Readline::History object editing in the [aia](https://github.com/MadBomber/aia) CLI tool
 
-### [0.2.0] - 2023-11-21
+## [0.2.0] - 2023-11-21
 
 - **Breaking change to FileSystemAdapter config process**
 - added list and path as extra methods in FileSystemAdapter
 
-### [0.1.0] - 2023-11-16
+## [0.1.0] - 2023-11-16
 
 - Initial release using the FileSystemAdapter