085607130a
feat: API catalog surface, protocol v2 tooling, MCP expansion, on+re update
## Summary
Session 2026-03-23. Closes the loop between handler code and discoverability
across all three surfaces (browser, CLI, MCP agent) via compile-time inventory
registration. Adds protocol v2 update tooling, extends MCP from 21 to 29 tools,
and brings the self-description up to date.
## API Catalog Surface (#[onto_api] proc-macro)
- crates/ontoref-derive: new proc-macro crate; `#[onto_api(method, path,
description, auth, actors, params, tags)]` emits `inventory::submit!(ApiRouteEntry{...})`
at link time
- crates/ontoref-daemon/src/api_catalog.rs: `catalog()` — pure fn over
`inventory::iter::<ApiRouteEntry>()`, zero runtime allocation
- GET /api/catalog: returns full annotated HTTP surface as JSON
- templates/pages/api_catalog.html: new page with client-side filtering by
method, auth, path/description; detail panel per route (params table,
feature flag); linked from dashboard card and nav
- UI nav: "API" link (</> icon) added to mobile dropdown and desktop bar
- inventory = "0.3" added to workspace.dependencies (MIT, zero transitive deps)
## Protocol Update Mode
- reflection/modes/update_ontoref.ncl: 9-step DAG (5 detect parallel, 2 update
idempotent, 2 validate, 1 report) — brings any project from protocol v1 to v2
by adding manifest.ncl and connections.ncl if absent, scanning ADRs for
deprecated check_hint, validating with nickel export
- reflection/templates/update-ontology-prompt.md: 8-phase reusable prompt for
agent-driven ontology enrichment (infrastructure → audit → core.ncl →
state.ncl → manifest.ncl → connections.ncl → ADR migration → validation)
## CLI — describe group extensions
- reflection/bin/ontoref.nu: `describe diff [--fmt] [--file]` and
`describe api [--actor] [--tag] [--auth] [--fmt]` registered as canonical
subcommands with log-action; aliases `df` and `da` added; QUICK REFERENCE
and ALIASES sections updated
## MCP — two new tools (21 → 29 total)
- ontoref_api_catalog: filters catalog() output by actor/tag/auth; returns
{ routes, total } — no HTTP roundtrip, calls inventory directly
- ontoref_file_versions: reads ProjectContext.file_versions DashMap per slug;
returns BTreeMap<filename, u64> reload counters
- insert_mcp_ctx: audited and updated from 15 to 28 entries in 6 groups
- HelpTool JSON: 8 new entries (validate_adrs, validate, impact, guides,
bookmark_list, bookmark_add, api_catalog, file_versions)
- ServerHandler::get_info instructions updated to mention new tools
## Web UI — dashboard additions
- Dashboard: "API Catalog" card (9th); "Ontology File Versions" section showing
per-file reload counters from file_versions DashMap
- dashboard_mp: builds BTreeMap<String, u64> from ctx.file_versions and injects
into Tera context
## on+re update
- .ontology/core.ncl: describe-query-layer and adopt-ontoref-tooling descriptions
updated; ontoref-daemon updated ("11 pages", "29 tools", API catalog,
per-file versioning, #[onto_api]); new node api-catalog-surface (Yang/Practice)
with 3 edges; artifact_paths extended across 3 nodes
- .ontology/state.ncl: protocol-maturity blocker updated (protocol v2 complete);
self-description-coverage catalyst updated with session 2026-03-23 additions
- ADR-007: "API Surface Discoverability via #[onto_api] Proc-Macro" — Accepted
## Documentation
- README.md: crates table updated (11 pages, 29 MCP tools, ontoref-derive row);
MCP representative table expanded; API Catalog, Semantic Diff, Per-File
Versioning paragraphs added; update_ontoref onboarding section added
- CHANGELOG.md: [Unreleased] section with 4 change groups
- assets/web/src/index.html: tool counts 19→29 (EN+ES), page counts 12→11
(EN+ES), daemon description paragraph updated with API catalog + #[onto_api]
144 lines
6.6 KiB
Plaintext
144 lines
6.6 KiB
Plaintext
let s = import "../schema.ncl" in
|
|
|
|
# Mode: adopt_ontoref
|
|
# Onboards an EXISTING project into the ontoref protocol.
|
|
# Creates missing pieces without overwriting existing files.
|
|
#
|
|
# Required params (substituted in cmd via {param}):
|
|
# {project_name} — identifier for this project (kebab-case)
|
|
# {project_dir} — absolute path to the existing project root
|
|
# {ontoref_dir} — absolute path to the ontoref checkout
|
|
|
|
{
|
|
id = "adopt_ontoref",
|
|
trigger = "Onboard an existing project into the ontoref protocol",
|
|
|
|
preconditions = [
|
|
"{project_dir} exists and is a directory",
|
|
"nickel is available in PATH",
|
|
"nu is available in PATH (>= 0.110.0)",
|
|
"{ontoref_dir}/templates/ontology/ exists (contains core.ncl, state.ncl, gate.ncl, manifest.ncl, connections.ncl stubs)",
|
|
"{ontoref_dir}/templates/ontoref-config.ncl exists",
|
|
"{ontoref_dir}/templates/scripts-ontoref exists",
|
|
],
|
|
|
|
steps = [
|
|
|
|
{
|
|
id = "create_ontoref_dir",
|
|
action = "create_config_directory",
|
|
actor = 'Agent,
|
|
cmd = "mkdir -p {project_dir}/.ontoref/logs {project_dir}/.ontoref/locks",
|
|
depends_on = [],
|
|
on_error = { strategy = 'Stop },
|
|
note = "Creates .ontoref/ directory structure. mkdir -p is idempotent.",
|
|
},
|
|
|
|
{
|
|
id = "copy_ontoref_config",
|
|
action = "copy_config_template",
|
|
actor = 'Agent,
|
|
cmd = "test -f {project_dir}/.ontoref/config.ncl || sed 's/{{ project_name }}/{project_name}/g' {ontoref_dir}/templates/ontoref-config.ncl > {project_dir}/.ontoref/config.ncl",
|
|
depends_on = [{ step = "create_ontoref_dir", kind = 'OnSuccess }],
|
|
on_error = { strategy = 'Stop },
|
|
note = "Copies config template only if .ontoref/config.ncl does not already exist.",
|
|
},
|
|
|
|
{
|
|
id = "create_ontology_dir",
|
|
action = "create_ontology_directory",
|
|
actor = 'Agent,
|
|
cmd = "mkdir -p {project_dir}/.ontology",
|
|
depends_on = [{ step = "create_ontoref_dir", kind = 'OnSuccess }],
|
|
on_error = { strategy = 'Stop },
|
|
note = "Creates .ontology/ directory. Idempotent.",
|
|
},
|
|
|
|
{
|
|
id = "copy_ontology_core",
|
|
action = "copy_ontology_core_stub",
|
|
actor = 'Agent,
|
|
cmd = "test -f {project_dir}/.ontology/core.ncl || sed 's/{{ project_name }}/{project_name}/g' {ontoref_dir}/templates/ontology/core.ncl > {project_dir}/.ontology/core.ncl",
|
|
depends_on = [{ step = "create_ontology_dir", kind = 'OnSuccess }],
|
|
on_error = { strategy = 'Stop },
|
|
note = "Copies core.ncl stub. Skipped if file already exists.",
|
|
},
|
|
|
|
{
|
|
id = "copy_ontology_state",
|
|
action = "copy_ontology_state_stub",
|
|
actor = 'Agent,
|
|
cmd = "test -f {project_dir}/.ontology/state.ncl || sed 's/{{ project_name }}/{project_name}/g' {ontoref_dir}/templates/ontology/state.ncl > {project_dir}/.ontology/state.ncl",
|
|
depends_on = [{ step = "create_ontology_dir", kind = 'OnSuccess }],
|
|
on_error = { strategy = 'Stop },
|
|
note = "Copies state.ncl stub. Skipped if file already exists.",
|
|
},
|
|
|
|
{
|
|
id = "copy_ontology_gate",
|
|
action = "copy_ontology_gate_stub",
|
|
actor = 'Agent,
|
|
cmd = "test -f {project_dir}/.ontology/gate.ncl || sed 's/{{ project_name }}/{project_name}/g' {ontoref_dir}/templates/ontology/gate.ncl > {project_dir}/.ontology/gate.ncl",
|
|
depends_on = [{ step = "create_ontology_dir", kind = 'OnSuccess }],
|
|
on_error = { strategy = 'Stop },
|
|
note = "Copies gate.ncl stub. Skipped if file already exists.",
|
|
},
|
|
|
|
{
|
|
id = "copy_ontology_manifest",
|
|
action = "copy_ontology_manifest_stub",
|
|
actor = 'Agent,
|
|
cmd = "test -f {project_dir}/.ontology/manifest.ncl || sed 's/{{ project_name }}/{project_name}/g' {ontoref_dir}/templates/ontology/manifest.ncl > {project_dir}/.ontology/manifest.ncl",
|
|
depends_on = [{ step = "create_ontology_dir", kind = 'OnSuccess }],
|
|
on_error = { strategy = 'Continue },
|
|
note = "Copies manifest.ncl stub for content assets and templates declaration. Skipped if file already exists.",
|
|
},
|
|
|
|
{
|
|
id = "copy_ontology_connections",
|
|
action = "copy_ontology_connections_stub",
|
|
actor = 'Agent,
|
|
cmd = "test -f {project_dir}/.ontology/connections.ncl || sed 's/{{ project_name }}/{project_name}/g' {ontoref_dir}/templates/ontology/connections.ncl > {project_dir}/.ontology/connections.ncl",
|
|
depends_on = [{ step = "create_ontology_dir", kind = 'OnSuccess }],
|
|
on_error = { strategy = 'Continue },
|
|
note = "Copies connections.ncl stub for cross-project federation addressing. Skipped if file already exists.",
|
|
},
|
|
|
|
{
|
|
id = "install_scripts_wrapper",
|
|
action = "install_consumer_entry_point",
|
|
actor = 'Agent,
|
|
cmd = "mkdir -p {project_dir}/scripts && test -f {project_dir}/scripts/ontoref || (sed 's|{{ ontoref_dir }}|{ontoref_dir}|g' {ontoref_dir}/templates/scripts-ontoref > {project_dir}/scripts/ontoref && chmod +x {project_dir}/scripts/ontoref)",
|
|
depends_on = [{ step = "create_ontoref_dir", kind = 'OnSuccess }],
|
|
on_error = { strategy = 'Stop },
|
|
note = "Installs scripts/ontoref thin wrapper. Skipped if already present.",
|
|
},
|
|
|
|
{
|
|
id = "validate_ontology",
|
|
action = "nickel_typecheck_ontology",
|
|
actor = 'Agent,
|
|
cmd = "cd {project_dir} && nickel export .ontology/core.ncl > /dev/null && nickel export .ontology/state.ncl > /dev/null && nickel export .ontology/gate.ncl > /dev/null",
|
|
depends_on = [
|
|
{ step = "copy_ontology_core", kind = 'OnSuccess },
|
|
{ step = "copy_ontology_state", kind = 'OnSuccess },
|
|
{ step = "copy_ontology_gate", kind = 'OnSuccess },
|
|
{ step = "copy_ontology_manifest", kind = 'Always },
|
|
{ step = "copy_ontology_connections", kind = 'Always },
|
|
],
|
|
on_error = { strategy = 'Stop },
|
|
note = "Validates all three .ontology/ files parse without errors.",
|
|
},
|
|
|
|
],
|
|
|
|
postconditions = [
|
|
"{project_dir}/.ontoref/config.ncl exists and is valid Nickel",
|
|
"{project_dir}/.ontology/core.ncl, state.ncl, gate.ncl exist and parse",
|
|
"{project_dir}/.ontology/manifest.ncl exists (content assets + templates declaration)",
|
|
"{project_dir}/.ontology/connections.ncl exists (cross-project federation stub)",
|
|
"{project_dir}/scripts/ontoref exists and is executable",
|
|
"No existing files were overwritten",
|
|
],
|
|
} | (s.Mode String)
|