spec: runbook-pack/v0.1
id: rtut.showcase-lighthouse
title: "Showcase: a night at the lighthouse"
owner: runbook-tutorials
outcome: You have played a short interactive story that touches every feature of the runbook engine, using only harmless echo, printf and a scratch file. Nothing outside /tmp/rtut-* is touched.
exercise_status: unexercised
engine: native
parameters:
  - {id: keeper, label: Your keeper's name, type: string, default: Ada, pattern: "[A-Za-z]+", help: One word. Used in the story.}
  - {id: lamp, label: Lamp fuel, type: enum, values: [whale-oil, paraffin, electric], default: paraffin, help: "Changes only the story text."}
  - {id: weather, label: Tonight's weather, type: enum, values: [clear, fog, storm], default: fog}
  - {id: signal, label: Warning signal, type: enum, values: [horn, flags], default: horn, help: "In fog the horn carries; in a storm, flags are lost. Choose well."}
  - {id: motto, label: The keeper's motto, type: text, default: Steady light for those at sea, help: A short phrase. Spaces are fine; quotes and shell symbols are not.}
  - {id: logdir, label: Scratch folder for the logbook, type: path, default: /tmp/rtut-lighthouse, pattern: "/tmp/rtut-[a-z0-9-]+", help: Must start with /tmp/rtut-. Removed at the end of the story.}
prerequisites:
  - {text: "A shell with echo, printf, cat and test (any Linux or macOS terminal)", owner: workstation}
  - {text: "Nothing else. No network, no accounts, no secrets", owner: nobody}
steps:
  - id: read-the-sign
    title: Read the poem over the door
    owner: the-lighthouse
    description: A read-only step with a manual check. The engine cannot know whether you read it, so it asks you.
    command: |
      printf '%s\n' 'Tower of stone, and a patient flame,' 'you keep no name, yet call each name' 'across the dark, across the foam:' 'come home, come home, come home.'
    verify:
      done_when: You read the poem and know what the light is for
      expect: manual
  - id: meet-the-keeper
    title: Meet the keeper
    owner: the-lighthouse
    description: Parameters appear inside commands. Change the name in the parameter form and this line changes.
    command: echo "{{keeper}} climbs the stairs. Motto on the wall - {{motto}}."
    verify:
      done_when: The line names your keeper
      command: echo "{{keeper}} climbs the stairs. Motto on the wall - {{motto}}."
      expect: output-contains
      contains: "{{keeper}} climbs"
  - id: light-the-lamp
    title: Light the lamp
    owner: the-lighthouse
    command: echo "{{keeper}} lights the {{lamp}} lamp."
    verify:
      done_when: The lamp is lit
      command: echo "{{keeper}} lights the {{lamp}} lamp."
      expect: output-contains
      contains: "lights the {{lamp}} lamp"
  - id: read-the-sky
    title: Read the sky
    owner: the-lighthouse
    command: echo "Weather tonight - {{weather}}."
    verify:
      done_when: You know tonight's weather
      command: echo "Weather tonight - {{weather}}."
      expect: output-contains
      contains: "{{weather}}"
  - id: sound-the-signal
    title: Sound the warning
    owner: the-lighthouse
    description: In a fuller runbook this would be a choice between alternatives. In v0.1 the choice is a parameter.
    command: echo "{{keeper}} works the {{signal}} through the {{weather}} night."
    verify:
      done_when: The signal is given
      command: echo "{{keeper}} works the {{signal}} through the {{weather}} night."
      expect: output-contains
      contains: "works the {{signal}}"
  - id: write-the-logbook
    title: Write tonight's entry in the logbook
    owner: the-lighthouse
    description: The only step that changes anything, and only a file under /tmp/rtut-. Reversible, so it needs a confirm, not a typed phrase.
    command: mkdir -p {{logdir}} && echo "Night watch by {{keeper}} - {{weather}}, {{lamp}} lamp, signal {{signal}}. {{motto}}." >> {{logdir}}/logbook.txt
    risk: changes-state
    rollback: rm -rf {{logdir}}
    verify:
      done_when: The logbook exists and is not empty
      command: test -s {{logdir}}/logbook.txt
      expect: exit-0
    evidence: [logbook_lines]
  - id: read-the-logbook
    title: Read the logbook back
    owner: the-lighthouse
    command: cat {{logdir}}/logbook.txt
    verify:
      done_when: The entry names your keeper
      command: cat {{logdir}}/logbook.txt
      expect: output-contains
      contains: "{{keeper}}"
  - id: dawn
    title: Put out the lamp and tidy up
    owner: the-lighthouse
    description: Removes the scratch folder. A run in which every step is done can offer to mark this pack exercised.
    command: rm -rf {{logdir}}
    risk: changes-state
    rollback: Repeat write-the-logbook to rebuild the entry.
    verify:
      done_when: The scratch folder is gone
      command: test ! -e {{logdir}}
      expect: exit-0
threat_checks:
  - This showcase never handles a secret. Parameters are never secret in any runbook; do not type one here to see what happens.
  - Only /tmp/rtut-* is ever written or removed; the folder pattern is enforced by the parameter.
ownership:
  - {concern: The story, owner: runbook-tutorials}