ontoref/reflection/modes/update_ontoref.ncl

let s = import "../schema.ncl" in

# Mode: update_ontoref
# Brings an EXISTING ontoref-adopted project up to the current protocol version.
# All steps are idempotent — safe to run multiple times and on already-current projects.
#
# What this mode adds (if not already present):
#   .ontology/manifest.ncl    — content assets and template declarations (v2)
#   .ontology/connections.ncl — cross-project federation addressing (v2)
#
# What this mode reports (advisory, no auto-migration):
#   ADRs with deprecated check_hint field — need manual migration to typed check
#   ADRs missing check field entirely     — not yet validated by the daemon
#
# What this mode verifies:
#   New files parse correctly under the current schema
#   Daemon /api/catalog is reachable (confirms daemon has v2 capabilities)
#
# Required params (substituted in cmd via {param}):
#   {project_name} — identifier for this project (kebab-case)
#   {project_dir}  — absolute path to the project root
#   {ontoref_dir}  — absolute path to the ontoref checkout

{
  id      = "update_ontoref",
  trigger = "Bring an existing ontoref project up to the current protocol version",

  preconditions = [
    "{project_dir}/.ontoref/config.ncl exists (project was previously adopted)",
    "{project_dir}/.ontology/core.ncl exists",
    "nickel is available in PATH",
    "nu is available in PATH (>= 0.110.0)",
    "{ontoref_dir}/templates/ontology/manifest.ncl exists",
    "{ontoref_dir}/templates/ontology/connections.ncl exists",
  ],

  steps = [

    # ── DETECT (all parallel, Continue — detection never blocks) ───────────────

    {
      id         = "detect-manifest",
      action     = "Detect whether .ontology/manifest.ncl is present",
      actor      = 'Agent,
      cmd        = "test -f {project_dir}/.ontology/manifest.ncl && echo 'present' || echo 'missing'",
      depends_on = [],
      on_error   = { strategy = 'Continue },
      note       = "Detection only — result informs add-manifest step.",
    },

    {
      id         = "detect-connections",
      action     = "Detect whether .ontology/connections.ncl is present",
      actor      = 'Agent,
      cmd        = "test -f {project_dir}/.ontology/connections.ncl && echo 'present' || echo 'missing'",
      depends_on = [],
      on_error   = { strategy = 'Continue },
      note       = "Detection only — result informs add-connections step.",
    },

    {
      id         = "detect-adr-hints",
      action     = "Scan ADRs for deprecated check_hint field",
      actor      = 'Agent,
      cmd        = "grep -rl 'check_hint' {project_dir}/adrs/ 2>/dev/null && echo 'MIGRATION NEEDED: check_hint found' || echo 'ok: no check_hint found'",
      depends_on = [],
      on_error   = { strategy = 'Continue },
      note       = "Advisory scan. ADRs using check_hint need manual migration to the typed check field.",
    },

    {
      id         = "detect-adr-no-check",
      action     = "Scan ADRs for constraints missing typed check entirely",
      actor      = 'Agent,
      cmd        = "grep -rL 'check =' {project_dir}/adrs/adr-*.ncl 2>/dev/null | head -20 || echo 'all ADRs have check field'",
      depends_on = [],
      on_error   = { strategy = 'Continue },
      note       = "Advisory scan. ADRs without check are not validated by the daemon's /validate/adrs endpoint.",
    },

    {
      id         = "detect-daemon-api",
      action     = "Check whether daemon exposes /api/catalog (v2 capability)",
      actor      = 'Agent,
      cmd        = "curl -sf ${ONTOREF_DAEMON_URL:-http://127.0.0.1:7890}/api/catalog > /dev/null && echo 'daemon: v2 api catalog available' || echo 'daemon: not reachable or pre-v2 (start/restart the daemon)'",
      depends_on = [],
      on_error   = { strategy = 'Continue },
      note       = "Non-blocking check. Daemon must be restarted to expose new API catalog endpoint.",
    },

    # ── UPDATE (parallel, Continue — each is individually idempotent) ──────────

    {
      id         = "add-manifest",
      action     = "Create .ontology/manifest.ncl stub if missing",
      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 = "detect-manifest", kind = 'Always }],
      on_error   = { strategy = 'Continue },
      note       = "Adds content asset and template declarations. Skipped if file already exists.",
    },

    {
      id         = "add-connections",
      action     = "Create .ontology/connections.ncl stub if missing",
      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 = "detect-connections", kind = 'Always }],
      on_error   = { strategy = 'Continue },
      note       = "Adds cross-project federation stub. Skipped if file already exists.",
    },

    # ── VALIDATE (depends on updates, Continue — partial success is still progress) ──

    {
      id         = "validate-manifest",
      action     = "Nickel typecheck .ontology/manifest.ncl",
      actor      = 'Agent,
      cmd        = "cd \"{project_dir}\" && nickel export --import-path \"{ontoref_dir}/ontology\" --import-path \"{ontoref_dir}/ontology/schemas\" --import-path \"{ontoref_dir}/ontology/defaults\" --import-path \"{ontoref_dir}\" .ontology/manifest.ncl > /dev/null",
      depends_on = [{ step = "add-manifest", kind = 'OnSuccess }],
      on_error   = { strategy = 'Continue },
      note       = "Confirms manifest.ncl parses under the current content schema. Quotes around {ontoref_dir} survive the macOS install path that contains a space (~/Library/Application Support/ontoref); --import-path repeated per directory instead of colon-separated to avoid splitting on the space when bash word-splits.",
    },

    {
      id         = "validate-connections",
      action     = "Nickel typecheck .ontology/connections.ncl",
      actor      = 'Agent,
      cmd        = "cd \"{project_dir}\" && nickel export --import-path \"{ontoref_dir}/reflection/schemas\" --import-path \"{ontoref_dir}\" .ontology/connections.ncl > /dev/null",
      depends_on = [{ step = "add-connections", kind = 'OnSuccess }],
      on_error   = { strategy = 'Continue },
      note       = "Confirms connections.ncl parses under the connections schema. Quoted paths + repeated --import-path flag for the same reason as validate-manifest.",
    },

    # ── REPORT (aggregate — depends on all previous steps) ────────────────────

    {
      id     = "report",
      action = "Print protocol update summary",
      actor  = 'Both,
      cmd    = "nu -c '
        print \"\"
        print $\"(ansi white_bold)ontoref protocol update — {project_name}(ansi reset)\"
        print \"\"

        let has_manifest    = (\"{project_dir}/.ontology/manifest.ncl\"    | path exists)
        let has_connections = (\"{project_dir}/.ontology/connections.ncl\" | path exists)

        print $\"  manifest.ncl     (if $has_manifest    { \"(ansi green)✓(ansi reset)\" } else { \"(ansi red)✗(ansi reset)\" })\"
        print $\"  connections.ncl  (if $has_connections { \"(ansi green)✓(ansi reset)\" } else { \"(ansi red)✗(ansi reset)\" })\"

        let hint_scan = (do { ^grep -rl check_hint {project_dir}/adrs/ } | complete)
        let hint_files = if $hint_scan.exit_code == 0 { $hint_scan.stdout | str trim | lines | where { |l| $l | is-not-empty } } else { [] }
        if ($hint_files | is-not-empty) {
          print \"\"
          print $\"  (ansi yellow_bold)ADR migration needed(ansi reset) — check_hint is deprecated; migrate to typed check field:\"
          for f in $hint_files { print $\"    (ansi yellow)($f)(ansi reset)\" }
          print \"    See: adrs/adr-schema.ncl for the typed check ADT\"
        } else {
          print $\"  ADR check fields  (ansi green)✓ up to date(ansi reset)\"
        }

        print \"\"
        print \"  New capabilities (daemon must be running):\"
        print \"    GET /api/catalog              — full annotated API surface\"
        print \"    GET /describe/guides          — actor-aware operational context\"
        print \"    GET /graph/impact?include_external=true — cross-project BFS\"
        print \"    GET /projects/{slug}/ontology/versions  — per-file change counters\"
        print \"    describe api                  — Nu command for API surface\"
        print \"    describe diff                 — semantic ontology diff vs HEAD\"
        print \"\"
      '",
      depends_on = [
        { step = "validate-manifest",    kind = 'Always },
        { step = "validate-connections", kind = 'Always },
        { step = "detect-adr-hints",     kind = 'Always },
        { step = "detect-daemon-api",    kind = 'Always },
      ],
      on_error = { strategy = 'Stop },
    },

  ],

  postconditions = [
    "{project_dir}/.ontology/manifest.ncl exists and parses",
    "{project_dir}/.ontology/connections.ncl exists and parses",
    "Report printed: ADR migration status, daemon capability checklist",
    "No existing files were overwritten",
  ],
} | (s.Mode String)