holivia 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db5748262c860764f5d29eb0fc184f3a1af3eb5bfb0456f11d51b0b0b42cb4ef
-  data.tar.gz: e4acfa1c1ffa4994f9bc5244be6e306e680a2dbed9605db234c1cb197e63f896
+  metadata.gz: 649b14e43fe74902dab26504ac1eb2ec403d3f7de0357283fb16393cd95e4d84
+  data.tar.gz: da1363943075ffbab5fa664434666202bc5654785a2e83083e6894c52d270baa
 SHA512:
-  metadata.gz: 557e344b1c20c531f9261345f7697ab404c660d3da956649b5912d5b095222c5eac68eb46883b66a6bd1b4b816cc62fdb6ce01896b52bbacd060cdafc01507dc
-  data.tar.gz: 74c71712389a8b2c9ce184e5385a3011cf3f2fc26304605bd23c996d862e1321c6be2cbb508b971b5df15b5a4be98bb0fb4c6f788e547a2bcdd616726cfdb0f0
+  metadata.gz: 497030e934ea60e03348f922f809811ef2f1d1172cd90c9a1b96533a26461d82a2dc6e2938cacf9a4e982ba30de93004edfb9e3f2ac79b9abc27247517312d2c
+  data.tar.gz: c36fa00ac0e7d9979ab1502a08143795b6ee7b97d3bafee411778d018c5ba96c34074a728cba00d4a44463de43bc96dc2724a6bc32065ea595da049079da491e

data/.agents/skills/add-holivia-cli-endpoint/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: add-holivia-cli-endpoint
+description: Add, extend, or review Holivia Ruby CLI commands that expose API endpoints while preserving the repository's routing, option parsing, HTTP, JSON output, help, and Minitest conventions. Use when implementing a new top-level CLI resource, adding an action or CRUD endpoint to an existing resource, exposing filters or request fields, adding multipart uploads, or checking an endpoint implementation for architectural consistency.
+---
+
+# Add a Holivia CLI Endpoint
+
+Read `../../../ai-skills/add-holivia-cli-endpoint.md` completely before taking any task action. Treat that file as the canonical workflow and follow it for the rest of the task.
+
+If the file cannot be read, stop and report that the canonical guide is unavailable instead of reconstructing its instructions from memory.

data/.agents/skills/add-holivia-cli-endpoint/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Add Holivia CLI Endpoint"
+  short_description: "Add API endpoints using the existing CLI design"
+  default_prompt: "Use $add-holivia-cli-endpoint to add this API endpoint consistently to the Holivia CLI."

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-17
+
+- Add repeatable `--topic-id` support to replace or clear topics assigned to selfcare content
+- Add CLI endpoint development skill documentation
+
 ## [0.9.0] - 2026-07-11
 
 - Add `holivia highlight` commands for HR home highlight CRUD, publishing, schema discovery, and cover/document uploads

data/README.md

@@ -148,6 +148,18 @@ Create and update commands also accept JSON from standard input:
 printf '{"title":"Breathing exercise","locale":"fr"}' | holivia selfcare create
 ```
 
+Replace the topics assigned to an existing content by repeating `--topic-id`:
+
+```bash
+holivia selfcare update 123 --topic-id topic-id-1 --topic-id topic-id-2
+```
+
+Pass an empty `topic_ids` array through stdin to remove every assigned topic. Omitting topic IDs leaves existing assignments unchanged:
+
+```bash
+printf '{"topic_ids":[]}' | holivia selfcare update 123
+```
+
 List objectives:
 
 ```bash

data/SKILL.md

@@ -179,6 +179,14 @@ Update a content:
 holivia selfcare update 123 --title "Updated title" --state published
 ```
 
+Replace the topics assigned to an existing content by repeating `--topic-id`:
+
+```bash
+holivia selfcare update 123 --topic-id topic-id-1 --topic-id topic-id-2
+```
+
+Pass `{"topic_ids":[]}` through stdin to clear all topic assignments. Omit topic IDs to leave assignments unchanged.
+
 Upload or replace an image:
 
 ```bash

data/ai-skills/add-holivia-cli-endpoint.md

@@ -0,0 +1,124 @@
+# Add a Holivia CLI Endpoint
+
+Keep endpoint commands thin and consistent with the nearest existing resource. Implement the API contract at the command layer; reuse the shared client for transport, authentication, retries, response parsing, and API errors.
+
+## Inspect Before Editing
+
+1. Read `CLAUDE.md` and check the worktree for user changes.
+2. Establish the endpoint contract from the request or authoritative API material: HTTP verb, exact path, path parameters, query parameters, body keys and types, file fields, response shape, and required CLI name. Do not invent missing contract details.
+3. Read these architecture files:
+   - `lib/holivia/cli.rb` for top-level registration.
+   - `lib/holivia/commands/base.rb` for the shared client, JSON output, and piped JSON.
+   - `lib/holivia/client.rb` for supported HTTP methods and request behavior.
+   - `lib/holivia/cli/help.rb` for user-facing discovery.
+   - `test/holivia/test_cli.rb` for routing and help expectations.
+4. Choose the closest command and test pair as the implementation model:
+   - Read-only collection/member: `objective.rb` or `enterprise.rb`.
+   - Single member action: `appointment.rb`.
+   - CRUD with filters and nested JSON: `crisis.rb`.
+   - CRUD, schema, transitions, and uploads: `communication_item.rb`, `intervention_item.rb`, or `hr_home_highlight.rb`.
+   - Nested CLI namespace: `selfcare_objective.rb`, routed by `selfcare.rb`.
+5. Prefer extending the selected pattern over introducing an abstraction for one endpoint. Refactor shared behavior only when the task requires it or repetition has become material.
+
+## Place the Endpoint
+
+For a new top-level resource:
+
+1. Add `lib/holivia/commands/<resource>.rb` with `# frozen_string_literal: true` and `require_relative "base"`.
+2. Define `Holivia::Commands::<Resource> < Base` and an exact `BASE_PATH`, normally under `/api/v1/backoffice`.
+3. Add `.route(args)`: shift the subcommand, dispatch with a `case`, pass the remaining array to the instance method, and warn plus `exit 1` for unknown commands.
+4. Require the command in `lib/holivia/cli.rb` and route its public top-level name in `CLI.start`.
+5. Add aliases only when the product vocabulary requires them; test each intentional alias.
+
+For an endpoint belonging to an existing resource, add a subcommand and instance method to that command class. For a nested namespace, route through its parent command rather than adding another top-level command.
+
+Use kebab-case for multiword CLI tokens, snake_case for Ruby filenames, constants, API paths, and request keys, and PascalCase for command classes. Follow existing public vocabulary when it differs from the API resource name.
+
+## Implement Command Behavior
+
+Use these mappings:
+
+- Collection read: `client.get(BASE_PATH, params: params)`.
+- Member read: `client.get("#{BASE_PATH}/#{id}")`.
+- Create: `client.post(BASE_PATH, body: options)`.
+- Update: `client.patch("#{BASE_PATH}/#{id}", body: options)`.
+- Member action: call the contract's verb on `"#{BASE_PATH}/#{id}/<action>"`.
+- Delete: call `client.delete`, then print `output(deleted: true, id: id.to_i)` when the server has no useful body.
+- Schema/discovery: `client.get("#{BASE_PATH}/schema")`.
+
+Do not instantiate Faraday directly in a command. Do not add authentication headers, retry logic, response parsing, or `ApiError` rescue there; `Client` and `exe/holivia` already own those concerns. Extend `Client` and its tests only if the API requires an unsupported HTTP capability.
+
+Always pass successful API responses to `output`, which preserves pretty-printed JSON as the CLI's machine-readable interface. Do not reshape a response unless the endpoint contract explicitly calls for it.
+
+### Parse arguments
+
+- Accept positional member IDs first with `id = args.shift`.
+- Abort missing IDs with the full command usage, for example `abort "Usage: holivia widget show <id>" unless id`.
+- Use `OptionParser` and set a complete `opts.banner`.
+- Map `--kebab-case` flags to snake_case symbol keys.
+- Apply `Integer` converters to numeric identifiers, pagination, counts, and durations. Preserve strings such as UUIDs, codes, timestamps, states, and locales.
+- Collect repeatable array flags by appending to an initialized array. Parse explicitly JSON-valued flags with `JSON.parse(..., symbolize_names: true)` when the resulting object is part of a symbol-keyed body.
+- Keep collection filters in `params`; keep create/update values in `options`.
+- For create and update, merge `piped_json` after flags with `options.merge(piped_json)`. This intentionally makes stdin JSON win on duplicate keys.
+- Abort an empty create/update body with `No options provided. Use --help for usage.`
+- Let the server validate domain rules and enums unless the repository already performs that validation. Expose a schema endpoint when the API provides one.
+
+Extract a shared private `add_write_options` method when create and update accept the same fields. Keep action helpers such as `transition(args, event)` private when several subcommands share the same shape.
+
+### Handle uploads
+
+Convert file paths to `Faraday::Multipart::FilePart` in a private body builder. Duplicate the options hash before replacing paths so the parser result is not mutated unexpectedly. Use a frozen extension-to-MIME map and fall back to `application/octet-stream`. Reuse the existing multipart-enabled `Client`; do not set the content type manually.
+
+Test every supported MIME mapping, the fallback, and each file field's conversion. Do not add client-side size or presence validation unless requested; API validation remains authoritative.
+
+## Update Discovery Surfaces
+
+Add the command, its arguments, and a concise description to the appropriate section of `lib/holivia/cli/help.rb`. Add or adjust the help assertions in `test/holivia/test_cli.rb`.
+
+Update `README.md` and the root operational `SKILL.md` only when the endpoint changes the documented primary workflow or should be available to agents operating the released CLI. Do not bump the gem version or edit release notes unless the user requests release preparation.
+
+## Test at the Command Boundary
+
+Create or update `test/holivia/commands/test_<resource>.rb`. Follow the nearest test file rather than introducing a new framework.
+
+1. Require `test_helper`, the command file, and `tmpdir` when used.
+2. Stub `$stdin` as a TTY in setup for commands that call `piped_json`; restore it in teardown.
+3. Stub `Holivia::Client.new` with a small object and restore the original method in `ensure`.
+4. Assert the exact HTTP method, endpoint path, query params or body, and representative JSON output.
+5. Cover every added behavior that applies:
+   - routing and unknown subcommand failure;
+   - filters and OptionParser type conversion;
+   - missing member ID;
+   - create/update with flags;
+   - piped JSON and its precedence when relevant;
+   - empty write rejection;
+   - member actions;
+   - delete confirmation;
+   - multipart parts and MIME detection;
+   - aliases;
+   - help visibility and top-level routing for a new resource.
+
+Keep these tests at the CLI-to-client boundary. Do not make network requests. Add `Client` tests only when changing transport behavior.
+
+## Verify and Review
+
+Run the narrow test first:
+
+```bash
+bundle exec ruby -Itest test/holivia/commands/test_<resource>.rb
+```
+
+Then run the repository checks:
+
+```bash
+bundle exec rake
+```
+
+Before finishing, inspect the diff and confirm:
+
+- Every endpoint path and verb matches the contract exactly.
+- Routing, requires, help text, and tests expose the same command spelling.
+- Query keys, body keys, and OptionParser types match the API.
+- Writes support stdin JSON consistently, unless the command is intentionally file-only or action-only.
+- Successful output is JSON and failures retain the shared executable behavior.
+- No unrelated refactor, version bump, credential, or generated package entered the change.

data/lib/holivia/cli/help.rb

@@ -27,7 +27,8 @@ module Holivia
           holivia selfcare create [options]      Create a selfcare content
                                                  (--state draft|ongoing_translation|translation_to_be_reviewed|
                                                   translation_reviewed|published)
-          holivia selfcare update <id> [options] Update a selfcare content (same --state values)
+          holivia selfcare update <id> [options] Update a selfcare content (same --state values;
+                                                 repeat --topic-id ID to replace assigned topics)
           holivia selfcare compose               Create a full content tree atomically (no audio)
           holivia selfcare schema                Show allowed values for content_types, format_types,
                                                  item_types, states, objective_tiers

data/lib/holivia/commands/selfcare.rb

@@ -77,6 +77,7 @@ module Holivia
           opts.on("--description DESC") { |v| options[:description] = v }
           opts.on("--image FILE") { |v| options[:image] = v }
           opts.on("--state STATE") { |v| options[:state] = v }
+          opts.on("--topic-id ID") { |v| (options[:topic_ids] ||= []) << v }
         end.parse!(args)
         options = options.merge(piped_json)
 

data/lib/holivia/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Holivia
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: holivia
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Holivia
@@ -45,6 +45,8 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".agents/skills/add-holivia-cli-endpoint/SKILL.md"
+- ".agents/skills/add-holivia-cli-endpoint/agents/openai.yaml"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CLAUDE.md
@@ -53,6 +55,7 @@ files:
 - README.md
 - Rakefile
 - SKILL.md
+- ai-skills/add-holivia-cli-endpoint.md
 - example_content.xml
 - examples/compose.json
 - exe/holivia