version: '3'

# ---------------------------------------------------------------------------
# cache.yml -- unified content cache + quarantine layer (#883 Story 2).
#
# Five-command surface (per the v1_scope.cache_commands list in
# vbrief/active/2026-05-05-883-deft-cache-quarantine-v1.vbrief.json):
#
#   - cache:put         (cache one (source, key) entry from a raw JSON file)
#   - cache:get         (print content.md path + meta.json contents)
#   - cache:invalidate  (delete the entry directory + append audit)
#   - cache:fetch-all   (orchestrate scm:* to bulk-populate a repo)
#   - cache:prune       (drop entries older than the threshold)
#
# Storage layout: .deft-cache/<source>/<key>/{raw.json, content.md, meta.json}
# plus the global .deft-cache/quarantine-audit.jsonl audit log. v1 ships
# the github-issue source only; 5 additional sources (github-pr,
# github-review, url, email, file) are deferred to v2 per the epic
# deferred_to_v2 list.
#
# Per `conventions/task-caching.md` (#574): every task here forwards
# `{{.CLI_ARGS}}` to a Python script, so NONE may declare `sources:` /
# `generates:` -- a go-task short-circuit would silently drop user-facing
# recovery flags (--force, --dry-run, --no-stale, etc.).
# ---------------------------------------------------------------------------

vars:
  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'

tasks:
  put:
    desc: "Cache an entry -- task cache:put -- <source> <key> --raw-file PATH [--ttl-seconds N]"
    dir: '{{.USER_WORKING_DIR}}'
    deps:
      - task: :engine:_ts-build
    cmds:
      - task: :engine:invoke
        vars:
          ENGINE_CMD: 'cache put {{.CLI_ARGS}}'

  get:
    desc: "Read an entry -- task cache:get -- <source> <key> [--allow-stale | --no-stale]"
    dir: '{{.USER_WORKING_DIR}}'
    deps:
      - task: :engine:_ts-build
    cmds:
      - task: :engine:invoke
        vars:
          ENGINE_CMD: 'cache get {{.CLI_ARGS}}'

  invalidate:
    desc: "Drop an entry -- task cache:invalidate -- <source> <key> [--reason TEXT]"
    dir: '{{.USER_WORKING_DIR}}'
    deps:
      - task: :engine:_ts-build
    cmds:
      - task: :engine:invoke
        vars:
          ENGINE_CMD: 'cache invalidate {{.CLI_ARGS}}'

  fetch-all:
    desc: "Bulk populate -- task cache:fetch-all -- --source github-issue --repo OWNER/NAME [--batch-size N] [--delay-ms N] [--ttl-seconds N] [--no-refresh-closed to skip open→closed reconcile]"
    dir: '{{.USER_WORKING_DIR}}'
    deps:
      - task: :engine:_ts-build
    cmds:
      - task: :engine:invoke
        vars:
          ENGINE_CMD: 'cache fetch-all {{.CLI_ARGS}}'

  prune:
    desc: "Drop expired or LRU-evict -- task cache:prune -- [--older-than-days 30] [--source github-issue] [--dry-run] [--to-cap]"
    dir: '{{.USER_WORKING_DIR}}'
    deps:
      - task: :engine:_ts-build
    cmds:
      - task: :engine:invoke
        vars:
          ENGINE_CMD: 'cache prune {{.CLI_ARGS}}'

  # #1137 — reversible closed-entry archive (NOT TTL prune; never auto-wired)
  archive-closed:
    desc: "Reversible archive of closed github-issue cache entries (#1137). -- task triage:cache-archive -- [--dry-run] [--older-than-days 30] [--repo OWNER/NAME] [--json]"
    dir: '{{.USER_WORKING_DIR}}'
    deps:
      - task: :engine:_ts-build
    cmds:
      - task: :engine:invoke
        vars:
          ENGINE_CMD: 'cache archive-closed --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

  archive-list:
    desc: "List archived github-issue cache entries (#1137). -- task triage:archive-list -- [--repo OWNER/NAME] [--format=json] [--since ISO] [--limit N]"
    dir: '{{.USER_WORKING_DIR}}'
    deps:
      - task: :engine:_ts-build
    cmds:
      - task: :engine:invoke
        vars:
          ENGINE_CMD: 'cache archive-list --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

  restore-from-archive:
    desc: "Restore archived github-issue entry to live cache (#1137). -- task triage:restore-from-archive -- --issue N [--repo OWNER/NAME] [--force]"
    dir: '{{.USER_WORKING_DIR}}'
    deps:
      - task: :engine:_ts-build
    cmds:
      - task: :engine:invoke
        vars:
          ENGINE_CMD: 'cache restore-from-archive --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'