Merged
Conversation
…ses and address technical debt
…lementation status
New spec files: - specs/demo-cli.md: unified demo CLI (Priority 10 DEMO-4), demo isolation, Docker packaging, unit and integration test requirements - specs/object-ids.md: full-URI object ID format, DataLayer handling, blackboard key conventions, ADR requirement (TECHDEBT-3) - specs/embargo-policy.md: actor embargo policy record format and API endpoint (EP-01-* through EP-03-*) - specs/encryption.md: ActivityPub encryption/key management (all PROD_ONLY) Extended existing specs: - specs/case-management.md: CM-05-* object model relationships (Report/Case/Publication/VulnerabilityRecord), CM-06-* case update broadcast, CM-07-* CVD action rules API - specs/agentic-readiness.md: AR-07-* CVD action rules API endpoint New notes file: - notes/do-work-behaviors.md: scope limits for 'do work' BT behaviors, partially-implementable behaviors, reporting behavior notes, embargo policy prior art Updated: - specs/README.md: new spec files, updated implementation status - notes/README.md: new notes file entry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- diataxis-requirements.md: normalize IDs from DIAT-{CAT}_{NN}-{NNN}
to DF-NN-NNN format for consistency with all other spec files
- semantic-extraction.md: SE-01-004 rewritten to remove
implementation-specific language (ActivityPattern class reference)
- handler-protocol.md: HP-08-005 updated to use canonical field name
case_statuses per CM-03-006; remove stale '(currently...)' qualifier
- case-management.md: add CM-03-007 (RM re-engagement uses Join, not
Undo); add CM-08 section (domain model architecture separation)
- response-format.md: add RF-06-002 (asymmetric inbox routing: Accept/
Reject goes to initiating actor, not back to current inbox)
- prototype-shortcuts.md: add PROTO-06 (domain model separation deferred
for prototype; cross-references CM-08 and notes/domain-model-separation)
- README.md: update DF- prefix note, mention CM-08/PROTO-06/RF-06-002,
update implementation status date
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…phase - Mark DEMO-3.10–3.15 (manage_embargo_demo, manage_participants_demo) complete in IMPLEMENTATION_HISTORY.md (568 tests passing) - Update IMPLEMENTATION_PLAN.md gap analysis: DEMO-3 fully done; add DEMO-4 phase with 12 atomic tasks (DC-01–DC-06 coverage) - Elevate TECHDEBT-1/5 to MEDIUM priority per PRIORITIES.md PRIORITY 20; mark TECHDEBT-2 as subsumed into DEMO-4 - Replace stale 'Demo Script Gap Summary' in IMPLEMENTATION_NOTES.md with DEMO-4 isolation and Docker interaction mode risk notes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… teardown to enhance maintainability
Create vultron/demo/utils.py with demo_step, demo_check context managers and HTTP client helpers (DataLayerClient, logfmt, postfmt, reset_datalayer, discover_actors, init_actor_ios, post_to_inbox_and_wait, verify_object_stored, get_offer_from_datalayer, log_case_state, setup_clean_environment, check_server_availability, BASE_URL) extracted from initialize_case_demo.py. Update initialize_case_demo.py to import from vultron.demo.utils instead of defining utilities locally. All other demo scripts continue to work via their existing imports from initialize_case_demo. Satisfies DC-02-001 (partial): from vultron.demo.utils import demo_step, demo_check succeeds. Full completion (all scripts importing directly) is DEMO-4.2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…egration test setup
Update all 11 demo scripts in vultron/scripts/ to import demo_step, demo_check, and shared client helpers from vultron.demo.utils instead of defining them locally or chaining through initialize_case_demo. - 7 scripts: changed import source from initialize_case_demo to vultron.demo.utils (establish_embargo, transfer_ownership, suggest_actor, invite_actor, manage_embargo, manage_participants, status_updates) - 4 scripts: removed locally-defined duplicate utility functions and added full import from vultron.demo.utils (acknowledge_demo, manage_case_demo, receive_report_demo, initialize_participant_demo) No demo script now defines its own demo_step or demo_check. 568 tests pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…o/ (DEMO-4.3) Move 12 demo scripts to vultron/demo/ so they are importable as vultron.demo.<script_name> per DC-02-002. - Update test/scripts/ imports: vultron.scripts.X_demo → vultron.demo.X_demo - Update docker/Dockerfile CMDs to use vultron.demo module paths - All demos retain if __name__ == '__main__' invocability 568 tests pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…O-4.4) Add demo_environment() context manager to vultron/demo/utils.py that wraps setup_clean_environment() on entry and calls reset_datalayer(init=False) + clear_all_actor_ios() in a finally block on exit. Update all 12 demo scripts to use demo_environment() in their main() loop, replacing the bare setup_clean_environment() call. This guarantees DataLayer cleanup even when a demo raises an exception (DC-03-001, DC-03-003). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Create vultron/demo/cli.py: click-based CLI with sub-commands for all 12 API demo scripts plus a vultrabot group (pacman, robot, cvd) - Add 'all' sub-command that runs every demo in sequence, stops on first failure, and prints a human-readable pass/fail summary (DC-01-003, DC-01-004) - Register vultron-demo = vultron.demo.cli:main in pyproject.toml (DC-01-001) - Add click>=8.3.1 dependency Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The `main` click group callback now calls `logging.basicConfig(force=True)` at INFO level (WARNING was the silent default). Adds --debug flag for DEBUG level and --log-file option for optional file logging. Tests added in test/demo/test_cli.py verifying: - root logger is configured at INFO by default (DC-05-001) - --debug flag switches to DEBUG level - --debug option appears in --help output - each sub-command invokes the correct demo.main() (DC-05-004) - `all` sub-command invokes every demo exactly once (DC-05-002) - `all` exits non-zero on first failure (DC-05-003) Fixes: plan/BUGS.md "Demo Commands produce no visible output" Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…nal bugs and implementation notes
…ogs_retry_attempts failure
…ing failure The test passed in isolation but failed in the full suite because TestCliLogging tests invoke the Vultron demo CLI which calls logging.basicConfig(level=INFO, force=True), raising the root logger above DEBUG. TestCliSubCommands/TestCliAll (no teardown) left root at INFO; teardown_method compounded this by resetting to WARNING. Fix 1: Wrap the call in test_health_check_retry.py with caplog.at_level(logging.DEBUG) so the test explicitly declares the required capture level and is independent of external logger state. Fix 2: Change TestCliLogging.teardown_method to restore root logger to logging.NOTSET instead of logging.WARNING, reducing cross-test pollution. Note: vultron/api/v2/app.py sets root logger to DEBUG at import time, which is a separate concern documented in IMPLEMENTATION_NOTES.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… details from BUGS.md
Add `demo` Docker target and service to replace per-demo containers: - docker/demo-entrypoint.sh: if DEMO env var set, run that sub-command non-interactively; otherwise show help and drop to interactive bash - docker/Dockerfile: add `demo` target using the entrypoint script - docker/docker-compose.yml: add `demo` service depending on api-dev with condition: service_healthy; stdin_open/tty for interactive use Implements DC-04-001 and DC-04-002. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove 12 individual per-demo services from docker/docker-compose.yml and their corresponding build targets from docker/Dockerfile. The unified 'demo' service (DC-04-001) with its interactive entrypoint replaces them. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds a README for the demo suite covering: - Overview table of all 12 workflow demos and the vultrabot sub-group - Docker Compose usage (interactive and DEMO= non-interactive modes) - Direct invocation via vultron-demo CLI and python -m - Summary of shared utilities in vultron.demo.utils - Demo isolation via demo_environment context manager - Pointer to integration-test make target Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add '## Demo' section with example admonition to all 12 main howto pages in docs/howto/activitypub/activities/. Each admonition shows the relevant vultron-demo sub-command and the Docker Compose equivalent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…tError The griffe 2.0.0 stub and griffecli 2.0.0 packages conflicted with griffelib 2.0.0 in the shared griffe/ namespace. uv's installation left griffe/__init__.py absent, causing mkdocstrings-python to fail with ImportError: cannot import name 'Alias' from 'griffe'. Remove griffe>=2.0.0 and griffecli>=2.0.0 from pyproject.toml. griffelib>=2.0.0 alone provides the complete griffe Python module. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Create docs/tutorials/receive_report_demo.md walking a learner through running the receive-report demo end-to-end with Docker Compose. Covers five steps (clone, start container, run demo, read output, exit) and describes the three scenarios shown by the demo. Update docs/tutorials/index.md to replace the 'Coming Soon' placeholder with a link to the new tutorial. Register the tutorial in mkdocs.yml under 'Learning Vultron'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Covers all 11 remaining vultron-demo sub-commands (initialize-case, initialize-participant, invite-actor, suggest-actor, manage-participants, transfer-ownership, establish-embargo, manage-embargo, acknowledge, status-updates, manage-case) plus the 'all' sub-command. Also updates tutorials/index.md and mkdocs.yml nav to link the new page. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…4.19) - Add module/class/function docstrings to vultron/demo/cli.py and vultron/demo/utils.py (all previously missing) - Add _setup_logging docstring to all 12 demo scripts - Add missing function docstrings in receive_report_demo.py, acknowledge_demo.py, and vultrabot.py - Create docs/reference/code/demo/ with index.md, cli.md, utils.md, and demos.md using mkdocstrings directives - Register new reference pages in mkdocs.yml under Demo Package Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR unifies the Vultron demo scripts and Docker containers, introducing a single demo service with a click-based CLI (vultron-demo) that consolidates all 12 individual demo workflows. The change eliminates duplicate Docker targets, centralizes shared utilities, and improves demo isolation through a context manager pattern.
Changes:
- Unified Docker container: replaced 12 individual demo services with a single
demoservice using a unified entrypoint - Demo CLI: new click-based
vultron-democommand with sub-commands for each workflow plusallfor sequential execution - Shared utilities: extracted common setup/teardown logic to
vultron/demo/utils.py; introduceddemo_environmentcontext manager for isolation - Documentation: added tutorials (receive-report, other demos), reference docs for demo package, and demo admonitions in how-to guides
- Test improvements: centralized test fixtures, eliminated wait delays in test environment (4min → 28s)
- Integration testing: new
integration_tests/demo/with shell script and README
Reviewed changes
Copilot reviewed 89 out of 93 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
docker/docker-compose.yml |
Replaced 12 demo services with single demo service |
docker/Dockerfile |
Consolidated 12 demo targets into single demo target |
docker/demo-entrypoint.sh |
New entrypoint: runs vultron-demo ${DEMO} if set, else interactive shell |
vultron/demo/cli.py |
Unified CLI with sub-commands, all runner, and vultrabot sub-group |
vultron/demo/utils.py |
Shared utilities (DataLayerClient, context managers, setup/teardown) |
vultron/demo/*_demo.py (12 files) |
Updated imports to use vultron.demo.utils; added docstrings; use demo_environment context manager |
test/demo/conftest.py |
Shared client fixture; sets DEFAULT_WAIT_SECONDS=0.0 for fast tests |
test/demo/_helpers.py |
make_testclient_call factory eliminates duplicated test setup |
test/demo/test_*.py (12 files) |
Updated imports; use shared client fixture and testclient_call factory |
test/demo/test_cli.py |
New tests for CLI logging, sub-commands, all runner, and failure handling |
test/demo/test_receive_report_demo_bug.py |
New test documenting inbox item handling (strings vs objects) |
docs/tutorials/*.md |
New tutorials: receive-report demo, other demos, updated index |
docs/reference/code/demo/*.md |
New reference docs for CLI, utils, and demo scripts |
docs/howto/activitypub/activities/*.md (12 files) |
Added demo admonitions with CLI and Docker Compose examples |
mkdocs.yml |
Added tutorials and demo reference to navigation |
pyproject.toml |
Added click and griffelib dependencies; vultron-demo entry point |
uv.lock |
Updated lockfile (removed griffe/griffecli, kept griffelib) |
integration_tests/demo/*.sh |
Integration test script for running all demos in Docker |
integration_tests/README.md |
Documentation for integration testing |
Makefile |
New integration-test target |
specs/demo-cli.md |
New spec for unified demo CLI requirements |
specs/*.md (9 files) |
New and updated specs (encryption, embargo-policy, object-ids, diataxis, etc.) |
notes/*.md (3 files) |
New notes on do-work behaviors, diataxis framework, domain model separation |
plan/*.md (4 files) |
Updated priorities, implementation notes, history, and ideation |
prompts/*.md (3 files) |
Updated prompts for BUGFIX, BUILD, IDEATION, and PLAN |
wip_notes/design_notes.md |
Deleted file (moved to .gitignore) |
test/scripts/__init__.py |
Deleted empty file |
Marked bug fixed in plan/BUGS.md and documented fix in plan/IMPLEMENTATION_NOTES.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- AGENTS.md: update Demo Scripts key files map to vultron/demo/ (was vultron/scripts/), add cli.py and utils.py entries, add two missing demo scripts, fix test path (test/demo/ not test/scripts/); update demo_step/demo_check section to reflect shared vultron/demo/utils.py source; add docs relative-links rule to Miscellaneous tips - notes/codebase-structure.md: update Demo Script Lifecycle Logging section to reflect utils.py home; replace stale 'Demo Scripts Belong in vultron/demo/' migration note with current-state description; add Outbox Delivery gap and app.py root-logger side-effect notes - notes/activitystreams-semantics.md: fix manage_case_demo.py path (vultron/scripts/ -> vultron/demo/) - specs/README.md: mark DEMO-4 complete, update test count to 568, add Outbox delivery gap entry - plan/IMPLEMENTATION_PLAN.md: refresh gap analysis (#9) — DEMO-3 and DEMO-4 both complete; replace full DEMO-4 task list with COMPLETE stub; update date - plan/IMPLEMENTATION_HISTORY.md: add Phase DEMO-4 completion summary - plan/PRIORITIES.md: mark PRIORITY 10 (DEMO-4) complete Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…iles - notes/case-state-model.md: add CM-03-006 rename guidance (scope grep commands, recommend single-PR rename for case_statuses + participant_statuses) - notes/documentation-strategy.md: add note on sequence diagrams vs demo scripts review requirement - notes/docker-build.md (new): project-specific Docker build observations, image content scoping, dependency layer caching, general build checklist - notes/README.md: add docker-build.md to index table - plan/IMPLEMENTATION_NOTES.md: remove items now captured in notes/ Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ahouseholder
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Copilot Summary
This pull request introduces a unified demo CLI for Vultron, consolidating all demo scripts under a single
vultron-democommand and simplifying the Docker and documentation setup. The changes improve usability, maintainability, and documentation for running and testing demo workflows.Demo CLI Unification and Docker Simplification:
vultron-demoCLI entry point (vultron/demo/cli.py) for all demo scripts, replacing individual script entry points and Docker targets. Added shared utilities invultron/demo/utils.py. Updated references and documentation to use the new CLI. [1] [2]democontainer and service indocker/Dockerfileanddocker/docker-compose.yml, using a newdemo-entrypoint.shscript to handle interactive and non-interactive modes via theDEMOenvironment variable. [1] [2] [3] [4]Documentation Updates:
docs/reference/code/demo/cli.md.vultron/demo/utils.pyand updated references to test/demo paths. [1] [2]Developer Experience Improvements:
integration-testto run demo integration tests, streamlining local and CI workflows.These changes collectively modernize the demo experience, making it easier for users and developers to run, test, and document Vultron workflows.