Skip to content
Back to search

festival

Festival Methodology: fest and camp CLI integration and methodology guidance.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Obedience-Corp/festival with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Obedience-Corp/festival'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/obedience-corp--festival/badge.svg)](/listings/obedience-corp--festival)

HTML

<a href="/listings/obedience-corp--festival"><img src="/api/listings/obedience-corp--festival/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Replace the brackets and paste this into your coding agent. It will install Festival if needed, create one camp, and link your existing repository. Git is required.

Help me set up Festival for this goal: [what you want done and how you'll know it worked].
My existing repository is at: [full local path].

If `camp`, `fest`, or `festival` is missing, install Festival. On macOS with Homebrew, use `brew install --cask Obedience-Corp/tap/festival`. On macOS or Linux with Node.js, use `npm install -g @obedience-corp/festival`. On Windows x64, install Scoop, then run `scoop install git`, `scoop bucket add obedience https://github.com/Obedience-Corp/scoop-bucket`, and `scoop install obedience/festival` in PowerShell. After installing, run `festival doctor` to check the install.

Use the installer that owns the suite for updates. For Scoop, run `scoop update festival`. For a Festival-managed install, run `festival update` without `--force`.

Ask me for a camp name, a one-line description, and a mission. Create the camp with `camp create <name> -d "<description>" -m "<mission>"`. Read `camp create --help` before adding flags. Use `camp create` for this. Do not run `camp init` or `festival setup`. Use the camp path printed by the command (by default, `~/campaigns/<name>`).

Set up navigation for my shell, adding the following lines to its config only if they are missing. For zsh or bash, use `eval "$(camp shell-init <shell>)"` and `eval "$(fest shell-init <shell>)"`, replacing `<shell>` with `zsh` or `bash`. For fish, use `camp shell-init fish | source` and `fest shell-init fish | source`. For PowerShell 5.1 or 7, add `Invoke-Expression (& camp shell-init powershell | Out-String)` and `Invoke-Expression (& fest shell-init powershell | Out-String)` to `$PROFILE`. Tell me to open a new terminal and run `csw <name>`; you can keep working from the camp root.

From the camp root, run `camp project link <full-local-repo-path> --yes`. This leaves the repository in place, links it under `projects/`, and adds a `.camp` attachment file to it.

Read the camp and project instructions, then use `fest understand` to learn the workflow. Skills are optional. Create a festival for my goal, link it to the project with `fest link` from the festival directory, and run the `fest next` loop. Ask me when you need a decision. Show me the festival path so I can follow progress, and leave the results and verification evidence ready for review.

The [agent setup guides](https://docs.fest.build/getting-started/agents/) cover optional skills and integrations for your tool.

<details> <summary>Prefer to set up manually?</summary>

Choose one method. Each installs `camp`, `fest`, and the `festival` manager.

**macOS with Homebrew**

brew install --cask Obedience-Corp/tap/festival

**macOS or Linux with Node.js**

npm install -g @obedience-corp/festival

**Windows x64 with Scoop (PowerShell)**

Install [Scoop](https://scoop.sh/) first, then run:

scoop install git
scoop bucket add obedience https://github.com/Obedience-Corp/scoop-bucket
scoop install obedience/festival

Windows supports local Camp and Fest work. `camp sync --from`, `camp clone --from`, and artifact transfer to or from another camp are not available in this release.

Check the install and create one camp:

festival doctor
camp create my-camp

`camp create` asks for a description and mission. By default, it creates your camp at `~/campaigns/my-camp`. Enter the path printed by the command and link a repository you already use:

cd ~/campaigns/my-camp
camp project link /path/to/your-existing-repo

Replace the repository path with its full local path. Your repository stays where it is. Camp links it under `projects/` and adds a `.camp` attachment file to the repository. You can also [clone a project into the camp](https://docs.fest.build/cli-reference/camp/camp_project_add/).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "festival",
  3. "description": "Festival Methodology: fest and camp CLI integration and methodology guidance.",
  4. "owner": {
  5. "name": "Obedience Corp",
  6. "url": "https://obediencecorp.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "festival",
  11. "description": "Festival Methodology: goal-oriented project management for human-AI development workflows. Provides fest and camp CLI integration, automatic installation, and methodology guidance.",
  12. "version": "1.4.1",
  13. "source": "./claude-plugin",
  14. "author": {
  15. "name": "Obedience Corp",
  16. "url": "https://obediencecorp.com"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 541 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Festival: A vibe engineering framework
  2. ![Festival Banner](docs/images/festival_banner.png)
  3. <p align="center"><a href="https://github.com/Obedience-Corp/festival"><img src="https://img.shields.io/github/stars/Obedience-Corp/festival?style=social" alt="Star Festival on GitHub"></a> <a href="https://github.com/Obedience-Corp/festival"><img src="https://img.shields.io/badge/built%20with-Festival-7c3aed.svg" alt="Built with Festival"></a>
  4. </p>
  5. Vibe coding is a fast way to explore an idea, build a demo, or recreate
  6. something familiar. When you go beyond the demo, build something new, or work
  7. where a mistake could cost millions, you need more control over how the work
  8. gets done.
  9. **Vibe engineering means turning AI-assisted work into a process you can
  10. inspect, improve, and delegate repeatedly.** You define the outcome, review
  11. important decisions, and check the evidence behind the result. The aim is to
  12. let agents carry more of the work without having to babysit every step.
  13. Festival gives you the tools to build that process through **templates and
  14. configuration**: **Fest** for long-term goals and automated planning, **Camp**
  15. for shared context across sessions, and **Obey** for oversight and background
  16. orchestration. You shape how agents work, see where they need attention, and
  17. refine the process for the next run. Plans, decisions, progress, and checks stay
  18. in files and Git, so you can inspect the work and continue in another session.
  19. [Install Festival](#install-festival) · [Install Festival App](#install-festival-app) · [Try it on one real goal](#get-started) · [See a completed build](#see-festival-in-action) · [How it works](#how-the-components-fit-together) · [简体中文](README.zh-CN.md)
  20. ## Install Festival
  21. Choose one method for your system. Each installs the `festival` manager,
  22. `fest` for planning, and `camp` for managing workspaces. You’ll also need Git.
  23. **macOS with Homebrew**
  24. ```bash
  25. brew install --cask Obedience-Corp/tap/festival
  26. ```
  27. **macOS or Linux with Node.js 18 or later**
  28. ```bash
  29. npm install -g @obedience-corp/festival
  30. ```
  31. **Windows x64 with Scoop (PowerShell)**
  32. Install [Scoop](https://scoop.sh/) first, then run these commands in PowerShell.
  33. ```powershell
  34. scoop install git
  35. scoop bucket add obedience https://github.com/Obedience-Corp/scoop-bucket
  36. scoop install obedience/festival
  37. ```
  38. Check that the suite is ready from your terminal.
  39. ```sh
  40. festival doctor
  41. ```
  42. For native Linux packages and other install methods, see the
  43. [installation guide](https://docs.fest.build/getting-started/installation/).
  44. ## Install Festival App
  45. Festival App is an optional desktop terminal for the same repositories and plans
  46. you use with the CLI. Arrange terminals, files, and browser views in split panes,
  47. or open Festival Activity to see what changed across your projects.
  48. With Festival v0.3.34 or later installed, run this command as your regular user.
  49. ```sh
  50. festival install app
  51. ```
  52. If `app` is an unknown target, check `festival version` and update Festival
  53. using the package manager you installed it with.
  54. You can also [download Festival App directly](https://fest.build/app#download).
  55. See [Licensing](#licensing) for the terms that apply to the desktop app.
  56. [![Festival App running a plan beside a README, swapping the panes, then opening the project activity graph](docs/images/demos/festival-app.gif)](https://fest.build/app#walkthrough)
  57. ## See Festival in action
  58. Three completed festivals built the [CodeSignal Practice Simulator](https://github.com/Festival-Examples/codesignal-practice-simulator).
  59. Agents followed the `fest next` loop, with testing and review gates feeding
  60. findings back into fixes. The demo repository includes the plans, tasks,
  61. review findings, and verification evidence for each build.
  62. <p align="center">
  63. <a href="https://github.com/Festival-Examples/codesignal-practice-simulator/tree/main/festivals/codesignal-browser-assessment-simulator-CB0001"><img src="https://raw.githubusercontent.com/Festival-Examples/codesignal-practice-simulator/main/festivals/codesignal-browser-assessment-simulator-CB0001/codesignal-browser-assessment-simulator-CB0001.gif" alt="Festival execution replay: six phases advance to completion." width="440"></a>
  64. </p>
  65. [Explore the demo](https://github.com/Festival-Examples/codesignal-practice-simulator) ·
  66. [Inspect the three festivals](https://github.com/Festival-Examples/codesignal-practice-simulator/tree/main/festivals) ·
  67. [Watch all three replays](https://github.com/Festival-Examples/codesignal-practice-simulator#how-this-was-built)
  68. **Start with one goal in a repository you already use.** Keep your existing
  69. coding agent, let it help set up Camp and Fest, and review the result. Add Obey
  70. when you want the daemon to manage execution.
  71. [Set up with your agent](#get-started) · [Configure Obey](https://docs.fest.build/obey/getting-started/)
  72. ## How the components fit together
  73. ```mermaid
  74. flowchart TB
  75. accTitle: How Festival components work together
  76. accDescr: Fest supplies plans and tracks progress. Camp shares saved context across sessions. Obey launches and supervises agents through a background daemon. All three work with your agent sessions.
  77. subgraph festival["Festival: templates + configuration"]
  78. fest["Fest<br/>Long-term goals<br/>Automated planning"]
  79. camp["Camp<br/>Shared context<br/>Across agent sessions"]
  80. obey["Obey<br/>Overseer<br/>Background daemon"]
  81. end
  82. agents["Agent sessions<br/>Your providers and models"]
  83. fest <-->|Tasks and progress| agents
  84. camp <-->|Read and record context| agents
  85. obey -->|Launch and supervise| agents
  86. ```
  87. | Component | What it makes possible |
  88. | --- | --- |
  89. | [Fest](https://docs.fest.build/methodology/overview/) | **Long-term goals and automated planning.** Guides agents through planning workflows, breaks goals into phases and tasks, and tracks execution through review and approval gates. |
  90. | [Camp](https://docs.fest.build/methodology/campaigns/) | **Shared context and context management.** Organizes projects, worktrees, research, decisions, and work items so successive agent sessions can pick up the same work. |
  91. | [Obey](https://docs.fest.build/obey/) | **Oversight and background orchestration.** Runs a local daemon that tracks agent sessions, launches and supervises supported providers, and drives festival execution. Its companion `ob` CLI provides planning, review, and other developer commands. |
  92. A **camp** is the workspace around your goals. A **festival** is a larger goal
  93. inside it. Each camp can have its own projects, knowledge, templates, and
  94. working practices. Switch camps with `camp switch` (`csw`); a new agent session
  95. can read the saved plans and decisions before continuing the work.
  96. You can use Camp and Fest directly with an agent that reads files and runs
  97. commands, including Claude Code, Codex, Grok Build, Cursor, or OpenCode. Add Obey
  98. when you want daemon-managed execution; its [provider setup guide](https://docs.fest.build/obey/getting-started/)
  99. covers the providers it can launch and supervise.
  100. The `festival` command installs and updates the tools. The base suite includes
  101. `camp`, `fest`, and the `festival` manager. Install Obey separately with
  102. `festival install obey`, which adds both `obey` and `ob`.
  103. ## What would you hand off?
  104. Start with a real outcome that you can review. For example:
  105. - **A feature across repositories:** “Add account deletion to the API and web app. Cover it with tests and document how existing users are affected.”
  106. - **An investigation before a build:** “Investigate why this service slows down under load. Save the evidence, compare the options, and bring me a recommendation before changing production.”
  107. - **A recurring review:** “Review this week's dependency changes, flag compatibility risks, and prepare the updates for my approval.”
  108. The goal, constraints, and success criteria come from you. Your agent works through the plan and returns when it reaches a review point or a decision that needs you.
  109. [Explore the use cases](https://docs.fest.build/use-cases/) · [See example camps and festivals](https://github.com/Obedience-Corp/examples)
  110. ## Get started
  111. **Try it on one real goal.** Start with one repository and one goal you already want to finish. Use your existing coding agent to plan the work, execute it, and leave the results ready for review.
  112. ### 1. Set up with your agent
  113. Replace the brackets and paste this into your coding agent. It will install Festival if needed, create one camp, and link your existing repository. Git is required.
  114. ```text
  115. Help me set up Festival for this goal: [what you want done and how you'll know it worked].
  116. My existing repository is at: [full local path].
  117. If `camp`, `fest`, or `festival` is missing, install Festival. On macOS with Homebrew, use `brew install --cask Obedience-Corp/tap/festival`. On macOS or Linux with Node.js, use `npm install -g @obedience-corp/festival`. On Windows x64, install Scoop, then run `scoop install git`, `scoop bucket add obedience https://github.com/Obedience-Corp/scoop-bucket`, and `scoop install obedience/festival` in PowerShell. After installing, run `festival doctor` to check the install.
  118. Use the installer that owns the suite for updates. For Scoop, run `scoop update festival`. For a Festival-managed install, run `festival update` without `--force`.
  119. Ask me for a camp name, a one-line description, and a mission. Create the camp with `camp create <name> -d "<description>" -m "<mission>"`. Read `camp create --help` before adding flags. Use `camp create` for this. Do not run `camp init` or `festival setup`. Use the camp path printed by the command (by default, `~/campaigns/<name>`).
  120. Set up navigation for my shell, adding the following lines to its config only if they are missing. For zsh or bash, use `eval "$(camp shell-init <shell>)"` and `eval "$(fest shell-init <shell>)"`, replacing `<shell>` with `zsh` or `bash`. For fish, use `camp shell-init fish | source` and `fest shell-init fish | source`. For PowerShell 5.1 or 7, add `Invoke-Expression (& camp shell-init powershell | Out-String)` and `Invoke-Expression (& fest shell-init powershell | Out-String)` to `$PROFILE`. Tell me to open a new terminal and run `csw <name>`; you can keep working from the camp root.
  121. From the camp root, run `camp project link <full-local-repo-path> --yes`. This leaves the repository in place, links it under `projects/`, and adds a `.camp` attachment file to it.
  122. Read the camp and project instructions, then use `fest understand` to learn the workflow. Skills are optional. Create a festival for my goal, link it to the project with `fest link` from the festival directory, and run the `fest next` loop. Ask me when you need a decision. Show me the festival path so I can follow progress, and leave the results and verification evidence ready for review.
  123. ```
  124. The [agent setup guides](https://docs.fest.build/getting-started/agents/) cover optional skills and integrations for your tool.
  125. <details>
  126. <summary>Prefer to set up manually?</summary>
  127. Start with the [Festival CLI installation](#install-festival), then create your workspace.
  128. Windows supports local Camp and Fest work. `camp sync --from`,
  129. `camp clone --from`, and artifact transfer to or from another camp are not
  130. available in this release.
  131. Create your first camp in the terminal.
  132. ```bash
  133. camp create my-camp
  134. ```
  135. `camp create` asks for a description and mission. By default, it creates your camp at `~/campaigns/my-camp`. Enter the path printed by the command and link a repository you already use:
  136. ```bash
  137. cd ~/campaigns/my-camp
  138. camp project link /path/to/your-existing-repo
  139. ```
  140. Replace the repository path with its full local path. Your repository stays where it is. Camp links it under `projects/` and adds a `.camp` attachment file to the repository. You can also [clone a project into the camp](https://docs.fest.build/cli-reference/camp/camp_project_add/).
  141. Add the shell integration described below, then open your coding agent at the camp root and give it a goal.
  142. [Linux packages, the checksummed Windows ZIP, and other install methods](https://docs.fest.build/getting-started/installation/).
  143. </details>
  144. **Enable the shell integration.** The shell shortcuts (`csw`, `cgo`, `fgo`, `fls`, and `cr`) are shell functions, so they exist only in a shell that has loaded the integration. The setup prompt asks your agent to add it, but an agent cannot load it into a terminal you already have open. Check your shell config and add these lines if they are missing.
  145. For zsh, add to `~/.zshrc` (for bash, replace `zsh` with `bash` and use `~/.bashrc`):
  146. ```bash
  147. eval "$(camp shell-init zsh)"
  148. eval "$(fest shell-init zsh)"
  149. ```
  150. For fish, add to `~/.config/fish/config.fish`:
  151. ```fish
  152. camp shell-init fish | source
  153. fest shell-init fish | source
  154. ```
  155. Open a new terminal and run `type csw`. It should report a shell function. If it reports "not found", the lines are not in the config file your shell reads at startup. Homebrew, npm, and Linux package installs also ship a sourceable helper file that adds tab completion; the [shell setup guide](https://docs.fest.build/getting-started/shell-setup/) lists the path for each install method.
  156. ### 2. Give your agent a goal
  157. If you used the setup prompt, your agent already has your first goal. For manual setup or your next goal, tell it:
  158. > I want [what you want done]. Success means [what you will check]. Create a festival for it, link it to the project, and run the `fest next` loop. Show me the festival path and leave the results ready for review.
  159. <p align="center">
  160. <img src="docs/images/demos/tui-delegate.gif" alt="Grok Build receives a goal, reads Festival guidance, and creates a design work item and festival plan." width="700">
  161. </p>
  162. A real Grok Build session planning a sample app feature. The agent handles the planning commands; you review the proposed work.
  163. ### 3. Follow progress and review the result
  164. Your agent handles planning and execution, asking you when it reaches an approval point or needs a decision. You can focus on other work and review the results when they're ready.
  165. To check progress along the way, open another terminal at the festival path your agent gives you and run `fest watch`.
  166. When the work is ready, ask your agent to show you:
  167. - The result against your original goal and success criteria.
  168. - The changed files and commits in your project.
  169. - The test and review evidence, including failures, unresolved questions, and decisions that still need you.
  170. Use the saved festival plan and work records together with your project's Git history to review what happened before accepting the result.
  171. <p align="center">
  172. <img src="docs/images/demos/tui-fest-watch.gif" alt="The fest watch terminal view updates a festival tree as scripted sample tasks advance." width="700">
  173. </p>
  174. The progress view you can open alongside your agent. This recording demonstrates the real `fest watch` interface with scripted progress updates in a sample festival.
  175. **If the session ends:** point your next agent at the saved festival and ask it to continue from the linked project. The recorded plan, progress, and decisions give it a starting point.
  176. [Follow the video quick start](https://docs.fest.build/getting-started/quickstart/) to see setup, planning with Grok Build, and the progress view.
  177. ## Share a festival replay
  178. `fest gif` turns recorded festival progress into a GIF you can send and share:
  179. ```bash
  180. fest gif my-festival -o replay.gif
  181. fest gif --festival MF0001 --speed 2
  182. ```
  183. When a festival moves to completed, Fest creates `festival-replay.gif` and embeds
  184. it in `FESTIVAL_OVERVIEW.md`, with both files included in the completion commit.
  185. Use `fest gif --embed` to refresh it or add a replay to an older festival.
  186. See the [replay guide](https://docs.fest.build/guides/festival-replays/) for
  187. examples, sharing, and recovery.
  188. ## How the work stays coherent
  189. A festival is a **graph of work**, organized into phases, sequences, and tasks. Each task has context and completion criteria. Your agent uses `fest next` to find the next actionable step, does the work, checks the result, and records progress before continuing.
  190. That is the basis for **loop engineering** with Festival: repeatable planning, execution, review, and handoff loops. You can start with a lightweight `WORKFLOW.md`, build a full festival for a larger goal, or run separate festivals with agents in separate worktrees.
  191. The camp holds the context around those goals over the life of the work. Research can inform a design; that design can become a festival; its results and decisions remain available for the next goal.
  192. You can work on many projects at once. Over time, camps function more like custom agents, where small seeds of your intentions trigger hundreds or thousands of individual actions.
  193. Each camp has its own context and workflows, so switching camps changes how your agents work.
  194. Quality gates provide places to test and review. `fest validate` checks plan structure, and `fest commit` links commits to festival tasks. You review the actual output and verification evidence before accepting the result.
  195. [Loops & orchestration](https://docs.fest.build/guides/loops-and-orchestration/) · [Festival methodology](https://docs.fest.build/methodology/overview/) · [Work items](https://docs.fest.build/methodology/work-items/)
  196. ### Add background orchestration with Obey
  197. After installing the Festival suite, add Obey:
  198. ```bash
  199. festival install obey
  200. obey ping
  201. ob providers
  202. ```
  203. Follow the [Obey setup guide](https://docs.fest.build/obey/getting-started/) to
  204. check its service and configure a provider and model. From a planned festival,
  205. preview the execution context before starting the task loop:
  206. ```bash
  207. ob fest execute --dry-run
  208. ob fest execute
  209. ```
  210. Obey oversees the session while the agent works through the festival. Use
  211. `obey top` from the camp to follow sessions. For individual developer tasks,
  212. `ob` can plan from a spec, review a diff, or generate a commit message.
  213. Obey's binaries are publicly available even though its source repository is
  214. private. [Configuration](https://docs.fest.build/obey/configuration/) ·
  215. [Everyday use](https://docs.fest.build/obey/usage/) ·
  216. [Troubleshooting](https://docs.fest.build/obey/troubleshooting/)
  217. The `festival` manager also installs CLI plugins. Run `festival browse` to
  218. explore them, or read [suite and plugin management](https://docs.fest.build/getting-started/festival-manager/).
  219. ## Useful between the big goals, too
  220. - **Jump straight to the work.** `cgo p api` finds a matching project; `cgo f` takes you to festivals. Add the [shell integration](https://docs.fest.build/getting-started/shell-setup/) to enable these shortcuts.
  221. - **Switch camps.** `camp switch` moves between registered camps. `csw` is the shorthand.
  222. - **Find the next thing to pick up.** `camp workitem` brings intents, research, designs, and festivals into one work queue.
  223. - **Start fresh after a merged PR.** `camp fresh` syncs a project to its default branch and prunes merged branches. Preview with `camp fresh --dry-run` from that project first, including any configured branch creation or follow-up commands.
  224. [Everyday development with cgo and camp fresh](https://docs.fest.build/guides/everyday-development/)
  225. ## Explore the tools
  226. The GIFs play on this page at a readable size.
  227. <details>
  228. <summary>Create specialized camps and switch between them</summary>
  229. Once you have a camp for your first goal, you can add others for your job, side projects, or hobbies. Give each its own skills, workflows, and processes so your agents work the way you want in that context.
  230. ```bash
  231. camp create work
  232. csw work
  233. csw my-camp
  234. ```
  235. `csw` is the shorthand for `camp switch`. It requires the [shell integration](https://docs.fest.build/getting-started/shell-setup/). With no name, it opens the camp picker.
  236. <p align="center">
  237. <img src="docs/images/demos/tui-camp-create.gif" alt="One session creates two camps, answering the description and mission prompts, then csw switches the shell from my-camp to work." width="700">
  238. </p>
  239. This recording shows both camps being created in a fresh demo home, then switching between them. By default, the camps are at `~/campaigns/my-camp` and `~/campaigns/work`.
  240. </details>
  241. <details open>
  242. <summary>Move between projects, plans, and camps</summary>
  243. `cgo` jumps to a project or planning directory. `camp switch` moves between camps, and `csw` is the shorthand.
  244. <p align="center">
  245. <img src="docs/images/demos/cgo-navigation.gif" alt="cgo jumps between projects, festivals, and design directories, then csw, the shorthand for camp switch, changes camps." width="700">
  246. </p>
  247. </details>
  248. <details open>
  249. <summary>See your camps and the projects inside one</summary>
  250. `camp list` browses registered camps by org. Move through them, change a camp's status, and filter down to the active ones.
  251. <p align="center">
  252. <img src="docs/images/demos/tui-camp-list.gif" alt="camp list groups camps by org, marks one inactive, then filters to active camps." width="700">
  253. </p>
  254. `camp project list` browses the projects in the current camp, grouped by type.
  255. <p align="center">
  256. <img src="docs/images/demos/tui-project-list.gif" alt="camp project list shows projects grouped by type, with search and a jump into the selected project." width="700">
  257. </p>
  258. </details>
  259. <details open>
  260. <summary>Find work, capture an idea, and sort the inbox</summary>
  261. **Find work across the camp.** `camp workitem` brings intents, research, designs, and festivals into one searchable list.
  262. <p align="center">
  263. <img src="docs/images/demos/tui-workitems.gif" alt="The camp workitem dashboard shows work across the camp, with search and a preview pane." width="700">
  264. </p>
  265. **Capture an idea.** `camp intent add` saves it to the inbox for later.
  266. <p align="center">
  267. <img src="docs/images/demos/tui-intent-add.gif" alt="The camp intent add form captures an idea and saves it to the inbox." width="700">
  268. </p>
  269. **Sort the inbox.** `camp intent explore` lets you browse intents by status and read their details.
  270. <p align="center">
  271. <img src="docs/images/demos/tui-intent-explore.gif" alt="The camp intent explore interface groups intents by status with fuzzy search and a live preview." width="700">
  272. </p>
  273. </details>
  274. <details open>
  275. <summary>See which festivals are active and inspect a plan</summary>
  276. `fest list` groups festivals by status, so you can see what's active, ready, or still being planned.
  277. <p align="center">
  278. <img src="docs/images/demos/tui-fest-list.gif" alt="fest list groups festivals into active, ready, and planning states." width="700">
  279. </p>
  280. `fest show` opens the structure of a plan, from its phases down to individual tasks.
  281. <p align="center">
  282. <img src="docs/images/demos/tui-fest-show.gif" alt="fest show displays a festival's phase, sequence, and task tree and switches between plans." width="700">
  283. </p>
  284. </details>
  285. <details open>
  286. <summary>Start fresh after a merged change</summary>
  287. `camp fresh configure` sets the follow-up commands that run after a project syncs.
  288. <p align="center">
  289. <img src="docs/images/demos/tui-fresh-configure.gif" alt="camp fresh configure adds a follow-up command for one project, including what happens if that command fails." width="700">
  290. </p>
  291. `camp fresh` checks out the default branch, pulls, prunes merged branches, and runs those follow-ups.
  292. <p align="center">
  293. <img src="docs/images/demos/tui-fresh.gif" alt="camp fresh syncs main, deletes merged branches, runs a follow-up, and reports a work item it left in place." width="700">
  294. </p>
  295. </details>
  296. <details open>
  297. <summary>Add testing and review gates to a plan</summary>
  298. `fest gates apply` previews the quality gates it will add before applying them with approval.
  299. <p align="center">
  300. <img src="docs/images/demos/tui-fest-gates-apply.gif" alt="fest gates apply previews quality gates for the plan's sequences, then applies them with approval." width="700">
  301. </p>
  302. </details>
  303. <details open>
  304. <summary>Review old work and clear space for what's next</summary>
  305. `camp dungeon crawl` walks through stale work so you can choose what to keep or archive.
  306. <p align="center">
  307. <img src="docs/images/demos/tui-dungeon-crawl.gif" alt="camp dungeon crawl offers keep, archive, and skip choices for stale work, then records the result." width="700">
  308. </p>
  309. </details>
  310. <details open>
  311. <summary>Reach a camp on another machine</summary>
  312. `camp machine` lists computers camp can hop to, and can add one from your Tailscale network.
  313. <p align="center">
  314. <img src="docs/images/demos/tui-machine.gif" alt="camp machine explains hops, then picks a computer from the Tailscale network to add." width="700">
  315. </p>
  316. </details>
  317. <details open>
  318. <summary>Open the Festival installer</summary>
  319. `festival` opens the suite manager: install the tools, check the setup, and launch camp and fest.
  320. <p align="center">
  321. <img src="docs/images/demos/tui-festival.gif" alt="The festival installer home, with setup steps and menus for install, doctor, and the camp and fest launchpad." width="700">
  322. </p>
  323. </details>
  324. <details>
  325. <summary>Watch a longer Festival session <strong>(click to expand video preview)</strong></summary>
  326. An earlier Festival workflow recording at 16× playback speed. Use the setup instructions above for the current first-run path.
  327. <p align="center">
  328. <a href="https://youtu.be/FY6vm74oa8o"><img src="docs/images/demo_video_thumb.jpg" alt="Watch a longer Festival workflow session on YouTube." width="700"></a>
  329. </p>
  330. </details>
  331. [More video walkthroughs and demos](https://docs.fest.build/videos/)
  332. ## Fits the tools you already use
  333. **Can I keep my issue tracker?**
  334. Yes. Keep issues where your team coordinates, and use Festival for the agent's plan and work record. Intents and other work items live in files, so scripts or justfiles can connect them to an external service's API. Ask your agent to help build the connection you need. [See the workflow](https://docs.fest.build/compare/festival-vs-issue-trackers/).
  335. **Can I change agents partway through?**
  336. Yes. The next agent can read the same saved plan, decisions, and progress. Give it the festival location and access to the linked project. [Agent handoff guide](https://docs.fest.build/use-cases/ai-agent-handoff/).
  337. **Do I need a Festival account?**
  338. The CLI tools are free to use and run locally without a Festival account. Your agent's account, model costs, and permissions remain with the provider you choose.
  339. ## Keep going
  340. - [Join the Obedience Corp Discord](https://discord.gg/Rt7dDY6VqD): get help with Festival, compare workflows, and share what you build.
  341. - [Documentation](https://docs.fest.build/): guides, use cases, and CLI reference.
  342. - [First festival tutorial](https://docs.fest.build/tutorials/first-festival/): a hands-on walkthrough of the plan structure.
  343. - [Examples](examples/) and [templates](templates/): work you can inspect and adapt.
  344. - [Plugin authoring](https://docs.fest.build/guides/plugin-authoring/): extend `camp` and `fest` with your own commands.
  345. - [Report a bug or request a feature](https://github.com/Obedience-Corp/festival/issues): tell us what happened or what would help.
  346. - [Give feedback](https://fest.build/feedback/) or [read the blog](https://fest.build/blog/).
  347. If Festival is useful to you, **star this repository** to help other developers discover it. A bug report, a workflow you share, or an example of work you've handed off helps us improve it.
  348. ## Licensing
  349. The Festival CLI suite (`festival`, `fest`, and `camp`) is open source under the
  350. [Apache License 2.0](LICENSE).
  351. Obey (the `obey` daemon and the `ob` client) and Festival App are optional
  352. proprietary products from Obedience Corp. Their release terms apply whether you
  353. install them through the Festival CLI or download them directly. See the
  354. [binary distribution license](https://github.com/Obedience-Corp/obey-releases/blob/main/LICENSE)
  355. and the terms included with each release.
  356. Built by [Obedience Corp](https://obediencecorp.com/).
claude-plugin/hooks/scripts/ensure-festival.sh · Bundled script · 350 lines · 6 findings marked
  1. #!/usr/bin/env bash
  2. # Ensures fest and camp are installed and up-to-date. Runs on SessionStart.
  3. # - If missing: downloads and installs from GitHub releases with checksum verification.
  4. # - If installed: checks for newer version and offers update notification.
  5. set -euo pipefail
  6. INSTALL_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
  7. REPO="Obedience-Corp/festival"
  8. CACHE_DIR="${FESTIVAL_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/festival}"
  9. CHECK_FILE="${FESTIVAL_CHECK_FILE:-$CACHE_DIR/last-update-check}"
  10. DOWNLOAD_TIMEOUT_SECONDS="${FESTIVAL_DOWNLOAD_TIMEOUT_SECONDS:-120}"
  11. info() {
  12. echo "$*" >&2
  13. }
  14. fail() {
  15. echo "$*" >&2
  16. exit 1
  17. }
  18. require_command() {
  19. local name="$1"
  20. command -v "$name" >/dev/null 2>&1 || fail "Required command not found: $name"
  21. }
  22. require_checksum_command() {
  23. if command -v shasum >/dev/null 2>&1 || command -v sha256sum >/dev/null 2>&1; then
  24. return 0
  25. fi
  26. fail "Required command not found: shasum or sha256sum"
  27. }
  28. check_installed() {
  29. command -v fest >/dev/null 2>&1 && command -v camp >/dev/null 2>&1
  30. }
  31. # Rate-limit update checks to once per day
  32. should_check_update() {
  33. if [ ! -f "$CHECK_FILE" ]; then
  34. return 0
  35. fi
  36. local last_check
  37. last_check=$(cat "$CHECK_FILE" 2>/dev/null || echo 0)
  38. local now
  39. now=$(date +%s)
  40. local age=$(( now - last_check ))
  41. # 86400 = 24 hours
  42. [ "$age" -ge 86400 ]
  43. }
  44. record_check() {
  45. mkdir -p "$(dirname "$CHECK_FILE")"
  46. date +%s > "$CHECK_FILE"
  47. }
  48. detect_platform() {
  49. OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  50. case "$OS" in
  51. darwin) OS="macOS" ;;
  52. linux) OS="linux" ;;
  53. *) echo "Unsupported OS: $OS" >&2; exit 1 ;;
  54. esac
  55. ARCH=$(uname -m)
  56. case "$ARCH" in
  57. x86_64|amd64) ARCH="x86_64" ;;
  58. arm64|aarch64) ARCH="arm64" ;;
  59. *) echo "Unsupported architecture: $ARCH" >&2; exit 1 ;;
  60. esac
  61. }
  62. fetch_release() {
  63. curl -fsSL --connect-timeout 10 --max-time "$DOWNLOAD_TIMEOUT_SECONDS" "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null
  64. }
  65. find_archive_url() {
  66. local release_json="$1"
  67. local url
  68. # Try exact OS-ARCH match first, then OS-all (universal binary, e.g. macOS-all)
  69. url=$(echo "$release_json" | grep '"browser_download_url"' | grep -i "${OS}" | grep -i "${ARCH}" | grep '\.tar\.gz"' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
  70. if [ -z "$url" ]; then
  71. url=$(echo "$release_json" | grep '"browser_download_url"' | grep -i "${OS}" | grep -i "all" | grep '\.tar\.gz"' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
  72. fi
  73. echo "$url"
  74. }
  75. extract_tag() {
  76. echo "$1" | grep '"tag_name"' | head -1 | sed -E 's/.*"([^"]+)".*/\1/'
  77. }
  78. download_file() {
  79. local url="$1"
  80. local dest="$2"
  81. local tmp="${dest}.tmp"
  82. rm -f "$tmp"
  83. curl -fsSL --connect-timeout 10 --max-time "$DOWNLOAD_TIMEOUT_SECONDS" "$url" -o "$tmp" || {
  84. rm -f "$tmp"
  85. return 1
  86. }
  87. mv "$tmp" "$dest"
  88. }
  89. checksum_url_for_archive() {
  90. local archive_url="$1"
  91. echo "${archive_url%/*}/checksums.txt"
  92. }
  93. sha256_file() {
  94. local file="$1"
  95. if command -v shasum >/dev/null 2>&1; then
  96. shasum -a 256 "$file" | awk '{print $1}'
  97. return 0
  98. fi
  99. sha256sum "$file" | awk '{print $1}'
  100. }
  101. expected_checksum() {
  102. local checksums_file="$1"
  103. local archive_name="$2"
  104. awk -v name="$archive_name" '$2 == name {print $1; found=1} END {exit found ? 0 : 1}' "$checksums_file"
  105. }
  106. verify_checksum() {
  107. local archive_path="$1"
  108. local checksums_path="$2"
  109. local archive_name="$3"
  110. local expected actual
  111. expected="$(expected_checksum "$checksums_path" "$archive_name")" || {
  112. echo "Checksum for ${archive_name} not found in checksums.txt" >&2
  113. return 1
  114. }
  115. actual="$(sha256_file "$archive_path")"
  116. if [ "$actual" != "$expected" ]; then
  117. echo "Checksum mismatch for ${archive_name}" >&2
  118. echo "expected: ${expected}" >&2
  119. echo "actual: ${actual}" >&2
  120. return 1
  121. fi
  122. }
  123. download_and_install() {
  124. local archive_url="$1"
  125. local archive_name checksums_url archive_path checksums_path
  126. archive_name="$(basename "$archive_url")"
  127. checksums_url="$(checksum_url_for_archive "$archive_url")"
  128. TMP_DIR=$(mktemp -d "${TMPDIR:-/tmp}/festival-plugin.XXXXXX")
  129. trap 'rm -rf "$TMP_DIR"' EXIT
  130. archive_path="${TMP_DIR}/${archive_name}"
  131. checksums_path="${TMP_DIR}/checksums.txt"
  132. download_file "$archive_url" "$archive_path" ||
  133. fail "Download failed. Install manually: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 165 on GitHub
  134. download_file "$checksums_url" "$checksums_path" ||
  135. fail "Checksum download failed. Install manually: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 168 on GitHub
  136. verify_checksum "$archive_path" "$checksums_path" "$archive_name" ||
  137. fail "Checksum verification failed. Install manually: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 171 on GitHub
  138. tar -xzf "$archive_path" -C "$TMP_DIR"
  139. mkdir -p "$INSTALL_DIR"
  140. for binary in fest camp; do
  141. extracted_path="$(find "$TMP_DIR" -type f -name "$binary" | head -1)"
  142. if [ -n "$extracted_path" ]; then
  143. install -m 0755 "$extracted_path" "${INSTALL_DIR}/${binary}"
  144. else
  145. fail "${binary} not found in ${archive_name}"
  146. fi
  147. done
  148. }
  149. # parse_local_fest_version SHORT_OUTPUT FULL_OUTPUT
  150. #
  151. # Prefer `fest version --short` (a single token: "dev", "v0.2.16", ...). If that
  152. # is empty (old binary, flag unknown), take field 2 of the first `fest version`
  153. # line ("fest v0.2.16" / "fest dev"). Do not scan the whole block for X.Y.Z:
  154. # the Go runtime line is `go: go1.26.4` and a greedy grep treats 1.26.4 as the
  155. # installed festival version.
  156. parse_local_fest_version() {
  157. local short="${1-}"
  158. local full="${2-}"
  159. local short_version
  160. short_version="$(printf '%s\n' "$short" | awk 'NR==1 {print $1; exit}')"
  161. if [ -n "$short_version" ]; then
  162. printf '%s' "$short_version"
  163. return 0
  164. fi
  165. printf '%s\n' "$full" | awk 'NR==1 {print $2; exit}'
  166. }
  167. # is_release_version TOKEN: 0 when TOKEN is a festival release semver
  168. # (optional leading v, X.Y.Z, optional -rc.N / dotted suffix). Rejects "dev",
  169. # empty, and *-dev.* snapshot builds.
  170. is_release_version() {
  171. local v="${1-}"
  172. case "$v" in
  173. ""|dev|unknown) return 1 ;;
  174. *-dev|*-dev.*) return 1 ;;
  175. esac
  176. printf '%s' "$v" | grep -Eq '^v?[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9.]+)?$'
  177. }
  178. # parse_bundle_version FULL_OUTPUT
  179. #
  180. # The festival suite version from `fest version`'s `bundle:` line, empty when
  181. # there is none. The line reads "bundle: festival vX.Y.Z", so the version is the
  182. # last field rather than field 2, and it is read through the semver grep so a
  183. # CRLF line ending or stray whitespace cannot ride along into the comparison.
  184. parse_bundle_version() {
  185. printf '%s\n' "${1-}" | grep '^bundle:' |
  186. grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true
  187. }
  188. # has_build_profile FULL_OUTPUT: 0 when `fest version` printed a `profile:`
  189. # line, which every bundle-capable fest does, bundled or not.
  190. has_build_profile() {
  191. printf '%s\n' "${1-}" | grep -q '^profile:'
  192. }
  193. # read_local_fest_version FULL_OUTPUT: fest's own release token, from an
  194. # already-captured `fest version` block plus a fresh `fest version --short`.
  195. read_local_fest_version() {
  196. local full="${1-}"
  197. local short
  198. short="$(fest version --short 2>/dev/null || true)"
  199. parse_local_fest_version "$short" "$full"
  200. }
  201. # print_update_notice CURRENT LATEST
  202. #
  203. # Prefer `festival update` when the hub binary is on PATH: it knows how the suite
  204. # was installed and runs or prints the package manager's command for Homebrew,
  205. # npm, AUR, and Scoop installs. install.sh would drop a second copy into
  206. # ~/.local/bin next to the package-manager copy.
  207. print_update_notice() {
  208. local current="$1" latest="$2"
  209. if command -v festival >/dev/null 2>&1; then
  210. info "Festival update available: ${current} -> ${latest}. Run: festival update"
  211. else
  212. info "Festival update available: ${current} -> ${latest}. Run: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 254 on GitHub
  213. fi
  214. }
  215. main() {
  216. require_command curl
  217. require_command tar
  218. require_command grep
  219. require_command sed
  220. require_command awk
  221. require_command find
  222. require_command install
  223. require_checksum_command
  224. detect_platform
  225. if ! check_installed; then
  226. info "Festival CLI not found. Installing fest and camp..."
  227. RELEASE_JSON=$(fetch_release) || {
  228. info "Could not fetch release info. Install manually: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 273 on GitHub
  229. exit 1
  230. }
  231. ARCHIVE_URL=$(find_archive_url "$RELEASE_JSON")
  232. if [ -z "$ARCHIVE_URL" ]; then
  233. info "No compatible archive found for ${OS}/${ARCH}. Install manually: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 279 on GitHub
  234. exit 1
  235. fi
  236. download_and_install "$ARCHIVE_URL"
  237. record_check
  238. if command -v fest >/dev/null 2>&1; then
  239. info "Festival installed successfully: $(fest version 2>/dev/null || echo 'fest ready')"
  240. else
  241. info "Installed to ${INSTALL_DIR}. You may need to add it to your PATH: export PATH=\"${INSTALL_DIR}:\$PATH\""
  242. fi
  243. exit 0
  244. fi
  245. # Already installed: check for updates (rate-limited to once/day)
  246. if ! should_check_update; then
  247. exit 0
  248. fi
  249. # This compares against the latest festival suite tag, so it needs the suite
  250. # version, not fest's own release. `fest version` distinguishes three cases:
  251. #
  252. # bundle: line a suite build; that line carries the version to compare
  253. # profile: line a bundle-capable fest that was not built from a suite
  254. # release (go install, just build)
  255. # neither a bundle published before either line existed, which
  256. # stamped the suite version into fest's own version field
  257. FEST_VERSION_OUTPUT="$(fest version 2>/dev/null)" || FEST_VERSION_OUTPUT=""
  258. CURRENT_VERSION="$(parse_bundle_version "$FEST_VERSION_OUTPUT")"
  259. if [ -z "$CURRENT_VERSION" ] && has_build_profile "$FEST_VERSION_OUTPUT"; then
  260. # A bundle-capable fest with no bundle line was never part of a suite
  261. # release, so there is no suite version to compare the tag against.
  262. # Saying anything here nags forever about an update the user did not
  263. # install and cannot apply, so record the check and stay quiet.
  264. record_check
  265. exit 0
  266. fi
  267. if [ -z "$CURRENT_VERSION" ]; then
  268. CURRENT_VERSION="$(read_local_fest_version "$FEST_VERSION_OUTPUT")"
  269. fi
  270. if ! is_release_version "$CURRENT_VERSION"; then
  271. if [ -n "$CURRENT_VERSION" ]; then
  272. info "Festival update check skipped: local fest version '${CURRENT_VERSION}' is not a release"
  273. fi
  274. record_check
  275. exit 0
  276. fi
  277. RELEASE_JSON=$(fetch_release 2>/dev/null) || {
  278. record_check
  279. exit 0
  280. }
  281. LATEST_TAG=$(extract_tag "$RELEASE_JSON")
  282. CURRENT_CLEAN="${CURRENT_VERSION#v}"
  283. LATEST_CLEAN="${LATEST_TAG#v}"
  284. record_check
  285. if [ "$CURRENT_CLEAN" != "$LATEST_CLEAN" ]; then
  286. print_update_notice "$CURRENT_VERSION" "$LATEST_TAG"
  287. fi
  288. }
  289. # Run main only when executed, not when sourced by the test harness.
  290. if [ "${BASH_SOURCE[0]:-$0}" = "$0" ]; then
  291. main "$@"
  292. fi
claude-plugin/hooks/scripts/ensure-festival.test.sh · Bundled script · 212 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # Unit tests for ensure-festival.sh version parsing and the update notice.
  3. #
  4. # Sources the installer (its main() is guarded so sourcing only defines
  5. # functions) and exercises parse_local_fest_version / is_release_version
  6. # against the SessionStart nag that treated `go: go1.26.4` as the installed
  7. # festival version, plus parse_bundle_version / has_build_profile, which decide
  8. # which of `fest version`'s three shapes carries a suite version to compare.
  9. # Pure string logic: no network, no temp dirs. Invoked by `just plugin check`.
  10. set -u
  11. DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  12. # shellcheck source=./ensure-festival.sh
  13. source "$DIR/ensure-festival.sh"
  14. fail=0
  15. check_parse() { # $1 want $2 short $3 full
  16. local want="$1" short="$2" full="$3" got
  17. got="$(parse_local_fest_version "$short" "$full")"
  18. if [ "$got" = "$want" ]; then
  19. if [ -n "${ENSURE_FESTIVAL_TEST_VERBOSE:-}" ]; then
  20. printf 'ok parse %-12s\n' "$want"
  21. fi
  22. else
  23. printf 'FAIL parse want=%s got=%s\n' "$want" "$got"
  24. fail=1
  25. fi
  26. }
  27. check_release() { # $1 want(yes|no) $2 token
  28. local want="$1" token="$2" got
  29. if is_release_version "$token"; then got=yes; else got=no; fi
  30. if [ "$got" = "$want" ]; then
  31. if [ -n "${ENSURE_FESTIVAL_TEST_VERBOSE:-}" ]; then
  32. printf 'ok release %-4s %s\n' "$want" "$token"
  33. fi
  34. else
  35. printf 'FAIL release want=%s got=%s %s\n' "$want" "$got" "$token"
  36. fail=1
  37. fi
  38. }
  39. check_bundle() { # $1 want $2 full
  40. local want="$1" full="$2" got
  41. got="$(parse_bundle_version "$full")"
  42. if [ "$got" = "$want" ]; then
  43. if [ -n "${ENSURE_FESTIVAL_TEST_VERBOSE:-}" ]; then
  44. printf 'ok bundle %-10s\n' "${want:-<none>}"
  45. fi
  46. else
  47. printf 'FAIL bundle want=%s got=%s\n' "$want" "$got"
  48. fail=1
  49. fi
  50. }
  51. check_profile() { # $1 want(yes|no) $2 full
  52. local want="$1" full="$2" got
  53. if has_build_profile "$full"; then got=yes; else got=no; fi
  54. if [ "$got" = "$want" ]; then
  55. if [ -n "${ENSURE_FESTIVAL_TEST_VERBOSE:-}" ]; then
  56. printf 'ok profile %-4s\n' "$want"
  57. fi
  58. else
  59. printf 'FAIL profile want=%s got=%s\n' "$want" "$got"
  60. fail=1
  61. fi
  62. }
  63. classic_full=$'fest dev\ncommit: 00bc23e\nbuilt: 2026-08-17T23:38:19Z\ngo: go1.26.4\nplatform: darwin/arm64'
  64. buggy="$(printf '%s\n' "$classic_full" | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)"
  65. if [ "$buggy" = "1.26.4" ]; then
  66. if [ -n "${ENSURE_FESTIVAL_TEST_VERBOSE:-}" ]; then
  67. printf 'ok fixture still reproduces the greedy grep\n'
  68. fi
  69. else
  70. printf 'FAIL fixture no longer reproduces the grep bug (got %s)\n' "$buggy"
  71. fail=1
  72. fi
  73. # --short is the version token; full output's Go line must not win.
  74. check_parse "dev" "dev" "$classic_full"
  75. check_parse "v0.2.16" "v0.2.16" $'fest v0.2.16\ngo: go1.26.4'
  76. check_parse "v9.8.7" "v9.8.7" $'fest v9.8.7\ngo: go1.26.4'
  77. # Fallback when --short is empty: field 2 of the first line, not a blob grep.
  78. check_parse "dev" "" "$classic_full"
  79. check_parse "v0.2.16" "" $'fest v0.2.16\ncommit: abc\ngo: go1.26.4'
  80. check_parse "" "" ""
  81. # Accidental full-block in the short slot: first field is "fest", never 1.26.4.
  82. check_parse "fest" "$classic_full" "$classic_full"
  83. check_release yes "v0.2.16"
  84. check_release yes "0.2.16"
  85. check_release yes "v9.8.7"
  86. check_release yes "v0.2.16-rc.1"
  87. check_release no "dev"
  88. check_release no ""
  89. check_release no "unknown"
  90. check_release no "fest"
  91. check_release no "go1.26.4"
  92. check_release no "v0.2.16-dev.3"
  93. check_release no "0.2.16-dev"
  94. # The three shapes of `fest version` the update check has to tell apart. The
  95. # suite build carries a bundle: line; a go install / just build carries only
  96. # profile:; a bundle published before either line existed carries neither.
  97. suite_full=$'fest v0.6.3\nbundle: festival v0.2.18\ncommit: 1a2b3c4\nbuilt: 2026-08-21T00:00:00Z\ngo: go1.26.4\nplatform: darwin/arm64\nprofile: stable'
  98. profile_only_full=$'fest v0.6.3\ncommit: 1a2b3c4\nbuilt: 2026-08-21T00:00:00Z\ngo: go1.26.4\nplatform: darwin/arm64\nprofile: stable'
  99. legacy_full=$'fest v0.2.17\ncommit: 98b9950e\nbuilt: 2026-08-10T00:00:00Z\ngo: go1.26.4\nplatform: darwin/arm64'
  100. suite_crlf="$(printf '%s\n' "$suite_full" | awk '{ printf "%s\r\n", $0 }')"
  101. # The bundle line is the suite version; fest's own v0.6.3 is not, and neither is
  102. # the Go line. A CRLF ending must not ride along into the comparison.
  103. check_bundle "v0.2.18" "$suite_full"
  104. check_bundle "v0.2.18" "$suite_crlf"
  105. # No bundle line: nothing to compare, whichever other lines are present.
  106. check_bundle "" "$profile_only_full"
  107. check_bundle "" "$legacy_full"
  108. check_bundle "" "$classic_full"
  109. check_bundle "" ""
  110. # profile: marks a bundle-capable fest, which is what separates "built outside a
  111. # suite release, stay quiet" from "old bundle, fest's own version is the suite
  112. # version".
  113. check_profile yes "$suite_full"
  114. check_profile yes "$profile_only_full"
  115. check_profile no "$legacy_full"
  116. check_profile no "$classic_full"
  117. check_profile no ""
  118. # The legacy shape still falls through to the existing parser, which reads the
  119. # suite version out of fest's own version field.
  120. check_parse "v0.2.17" "" "$legacy_full"
  121. check_parse "v0.2.17" "v0.2.17" "$legacy_full"
  122. check_release yes "$(parse_local_fest_version "" "$legacy_full")"
  123. # Whatever the shape, no read may ever return the Go toolchain version.
  124. for shape in "$suite_full" "$profile_only_full" "$legacy_full" "$classic_full"; do
  125. for got in "$(parse_bundle_version "$shape")" "$(parse_local_fest_version "" "$shape")"; do
  126. case "$got" in
  127. *1.26.4*)
  128. printf 'FAIL go toolchain version leaked into a version read: %s\n' "$got"
  129. fail=1
  130. ;;
  131. esac
  132. done
  133. done
  134. # Update notice: run main() end to end with a stub fest, a stubbed release
  135. # fetch, and an isolated HOME/cache so nothing touches the network or the real
  136. # home. PATH holds only the stub dir plus the system dirs, so `festival` is
  137. # present or absent on purpose.
  138. notice_tmp="$(mktemp -d "${TMPDIR:-/tmp}/ensure-festival-test.XXXXXX")"
  139. trap 'rm -rf "$notice_tmp"' EXIT
  140. mkdir -p "$notice_tmp/bin" "$notice_tmp/home"
  141. cat > "$notice_tmp/bin/fest" <<'EOF_FEST'
  142. #!/bin/sh
  143. case "$*" in
  144. "version --short") echo v0.3.20 ;;
  145. *) printf 'fest v0.3.20\nprofile: suite\nbundle: festival v0.3.20\n' ;;
  146. esac
  147. EOF_FEST
  148. printf '#!/bin/sh\nexit 0\n' > "$notice_tmp/bin/camp"
  149. printf '#!/bin/sh\nexit 0\n' > "$notice_tmp/bin/festival"
  150. chmod +x "$notice_tmp/bin/fest" "$notice_tmp/bin/camp" "$notice_tmp/bin/festival"
  151. run_notice() { # $1 with_festival(yes|no) $2 latest tag
  152. local with_festival="$1" latest="$2" festival_bin="$notice_tmp/bin/festival" hidden="$notice_tmp/bin/festival.off"
  153. rm -rf "$notice_tmp/cache"
  154. if [ "$with_festival" = no ] && [ -e "$festival_bin" ]; then mv "$festival_bin" "$hidden"; fi
  155. if [ "$with_festival" = yes ] && [ -e "$hidden" ]; then mv "$hidden" "$festival_bin"; fi
  156. (
  157. export HOME="$notice_tmp/home" FESTIVAL_CACHE_DIR="$notice_tmp/cache"
  158. export PATH="$notice_tmp/bin:/usr/bin:/bin"
  159. unset FESTIVAL_CHECK_FILE
  160. # shellcheck disable=SC2034
  161. CHECK_FILE="$FESTIVAL_CACHE_DIR/last-update-check"
  162. # shellcheck disable=SC2329
  163. fetch_release() { printf '{"tag_name": "%s"}\n' "$latest"; }
  164. main 2>&1
  165. )
  166. }
  167. check_notice() { # $1 name $2 want-substring ("" = no output) $3 forbidden-substring $4 with_festival $5 latest
  168. local name="$1" want="$2" forbid="$3" got
  169. got="$(run_notice "$4" "$5")"
  170. if [ -z "$want" ]; then
  171. if [ -n "$got" ]; then printf 'FAIL notice %s: want no output, got: %s\n' "$name" "$got"; fail=1; fi
  172. return
  173. fi
  174. case "$got" in
  175. *"$want"*) ;;
  176. *) printf 'FAIL notice %s: missing "%s" in: %s\n' "$name" "$want" "$got"; fail=1 ;;
  177. esac
  178. case "$got" in
  179. *"$forbid"*) printf 'FAIL notice %s: unexpected "%s" in: %s\n' "$name" "$forbid" "$got"; fail=1 ;;
  180. esac
  181. }
  182. check_notice "festival on PATH" "Festival update available: v0.3.20 -> v0.3.24. Run: festival update" "install.sh" yes v0.3.24
  183. check_notice "festival absent" "Run: curl -fsSL https://raw.githubusercontent.com/Obedience-Corp/festival/main/install.sh | bash" "Run: festival update" no v0.3.24
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 203 on GitHub
  184. check_notice "up to date, festival on PATH" "" "" yes v0.3.20
  185. check_notice "up to date, festival absent" "" "" no v0.3.20
  186. if [ "$fail" -ne 0 ]; then
  187. echo "ensure-festival version parse tests failed" >&2
  188. exit 1
  189. fi
  190. echo "ensure-festival version parse tests passed"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.