Add notes on how to update the Google sheets credentials

I had to reverse engineer this a little bit prior to the 2023 Mystery
Hunt, (by trying to use the "New Hunt" button in Turbot and finding an
error of "invalid_grant: Bad Request" coming from
gsheets_creds.refresh(Request()) in the CloudWatch logs for the turbot
lambda).

The new instructions here tell the admin how to update the Gsheets
credentials (by running ./gsheets-authenticate.py) and how to take the
value that results (in the .gsheets-pickle.base64 file) and put it
into the SSM parameter named GSHEETS_PICKLE_BASE64 in ASM Systems
Manager in the AWS interface.

Ignore flake8 E266

Which doesn't allow comments to include multiple hash symbols,
(seriously, the flake conformance can get out of hand sometimes).

Disable auto-invitation of members to each new puzzle channel

This is a temporary hack at the request of Avram who is still working
on MH 2022 puzzles even after the hunt is over, but he doesn't want to
disturb dozens of people with notifications of new channels.

Set hunt channel topic when initially creating the hunt

And not just when editing the hunt after the fact.

Include a link to the big board in the hunt channel's topic

Now that we are generating the big board views on halibut.cworth.org.

Add a stub for the turbot web view

Basically just to ensure we can distinguish a Slack request from any
other.

TODO: Drop a bunch of items that have been completed

It always feels great to check off items from a TODO list!

Add a state field to the "edit hunt" form

Also, put both the hunt url and the hunt state into the hunt channel's topic.

Add a list of users that don't want to be auto-invited to new channels

Starting the list of initially with Lavi's user ID.

Add code to auto-invite all users in a hunt to each new puzzle channel

We had originally written the code this way, long ago, but disabled it
(prior to MH 2021) when some people found it intrusive to be invited
to every channel, (rather than selecting the puzzles they were
interested in participating in). And after disabling it we also
deleted the code entirely in commit
ef8d8f359be149adbbdbeda88ec4b6bbbebf928e

Prior to MH 2022 we had talked about adding a user preference since
some people would like to be auto-invited. But then we got a lot less
code written than we'd wanted to before MH 2022.

So we decided to add the auto-join feature back, (so that people could
see channels that have huddle icons for easily determining puzzles
that have active activity).

Abbreviate round name to only 7 characters in Slack channel name

Some users were nervous about the round portion of the channel name
overwhelming the space available for channel names, making it
impossible to distinguish one puzzle channel from another in the same
round. Restricting the round prefix to only 7 letters should help
mitigate that.

Announce to the hunt whenever a puzzle receives a new tag

This will hopefully help people stay abreast of puzzles that they are
most interested in (by having a central place to see which tags are
being added to puzzles).

Add tags field to the new_puzzle and edit_puzzle forms

This completes the puzzle edit form so that all state that can be
manipulated with slash commands can also be directly edited with the
interactive dialog form.

Add a /delete command

Which performs automated archiving of all channels for an inactive hunt.

Don't set a channel description longer than 250 character.

Oops. The Slack channel description _is_ just as limited as the
channel topic, (only 250 characters). So we have to trim it just like
we trim the channel topic.

At least the description has the title first, so different information
will appear in the topic and description and hopefully everything
necessary at least appears in one place or the other.

Use common code for setting the channel topic and description

Previously, the initial setting of the topic and description was with
custom code, separate from the code that set the topic later due to
puzzle edits. Because of this code duplication, the formatting of
these two sets of code had drifted already. Making the initial setting
of topic use the existing puzzle_channel_topic() function eliminates
the code duplication.

Similarly, we give the channel description the same treatment that we
were already giving the channel topic. That is, we update it whenever
a puzzle edit would cause it to change. While we're doing that, and
since the puzzle description doesn't have the same short limit as the
channel topic, we expand it to be longer, (previously it was the same
text as the initial channel topic). So the new
puzzle_channel_description constructs a more verbose description which
now includes the puzzle title (which the channel topic no longer
includes after the previous commit), and also some helpful message
about links and commands.

Don't put the puzzle name into the channel topic

Since hunt writers do various things to torture us, (see Infinite
Corridor), and since the channel topic has a small limit, don't put
the puzzle title into the topic. Otherwise, a long puzzle title could
force the important links to not appear at all in the topic.

puzzle_copy: Copy the solution list as well

Otherwise, the new puzzle will be pointing at the old puzzle's
solution list, (and the code that looks to see if the solution list
has changed won't notice any change).

This fixes things so that using "/solved" to add a second (or third,
...) to a puzzle will now update the channel's topic, which wasn't
happening before.

Fix a typo in the message announcing a puzzle solution

This typo was visible to users and annoying ungrammatical.

Fix a type in a comment

Just had the word "the" where I meant to have "then".

Use empty list instead of empty tuple in a few places

I don't think the type actually mattered anywhere here, but it might have.
(Leave it to python and its annoying type unsafety to be unhelpful here.)

Convert the solution data structure back to a list, (but still avoid dupes.)

The put_item call was not happy receiving a set object. So, instead of using
one, we use a lits and just take care to not add any duplicates to the list.

Use a set instead of a list for a puzzle's solution

This allows for cleaner handling when two solvers submit the same
solution back-to-back. Previously the identical solution would appear
multiple times in the list of solutions which was obviously not
helpful.

Now, each solution will appear no more than once.

Fix puzzle edit form in the case of no existing rounds in the hunt yet

This was a corner case affecting only the first few puzzles or so, (before
any puzzles were associated with a round).

Remove the util code

This was getting in the way of deployment, (since it's not flake8-clean).

Instead of fixing it, just nuke it. We weren't certain we'd ever use it
anyway, (and it's now at least in git revision history if needed).

Move all Turbot-created sheets down one level (in google drive)

The new folder is named "turbot"

Add some utility code

None of this is really "part of" turbot, but is instead some
standalone code I've written from time to time either while testing
functionality or when live-tweaking something during hunt as follows:

sheets-test.py: Ensuring Google sheets API works as expected

blocks-test.py: Debugging some Slack blocks formatting

hunt-channel-topic-tweak.py: During MH 2021 it was useful (for
a reason I don't recall at the moment) to be able to manually
tweak the topic of some channels from a script and I whipped
these up at the moment.

It's not clear if any of this will be useful going forward, but just
in case I'm holding onto it for now. We may just want to delete this
code if we find we don't end up using it.

Ignore the .gsheets.env file if it exists

I've had this around for some utility code and don't want "git status"
saying anything about it.

Edit the help messages for "new" and "edit"

The old help messages were confusing. It wasn't always clear that
"[puzzle]" meant an optional argument of literally the word "puzzle"
rather than the name of a particular puzzle to edit.

Instead, we encourage people to use these commands without arguments
(whenever possible, such as "/edit" for hunt or puzzle and "/new" for
puzzle) and to use clear literal arguments when necessary (such as
"/new hunt" from any channel or "/edit hunt" from within a puzzle
channel).

Add a README file for turbot

If nothing else, this will be helpful to remind me what the email
addresses are that I've been using for AWS and Google Drive accounts,
and also what the URL is for editing the Turbot app.

Remove some recently-added debugging print statements

After determining the actual problem.

Fix "New Hunt" button to actually call new_hunt_button function

Was previously calling new_hunt function directly which cannot work.

Add some debugging of the turbot home app

I'm getting some "channel_not_found" errors that I don't understand,
because I don't think I have any active hunts currently.

Add a couple of more TODO items

These were left over from the Hunt in January 2021.

Fix missing case of nested array

Hoping we're there now with this fix?

Restrict list of blocks to 100 items

Since I've now seen Slack complaining if lists are greater than 100 items.

Live fix for apparently overflowing the Slack message limit with hunt details

Condense the Turbot Home view to only link to hunts, not give all the
details.

Change hunt_blocks() function to return an array of array of blocks,
(broken up at the level of a round). Callers now generate one post for
each element in the outer array. Hopefully this gives us a little
breathing room for now.

Add some recent TODO items

These obviously aren't going to happen or this year, but we can
consider them for future years.

When creating a new puzzle, set default rounds based on current puzzle

This happens when running the puzzle creation command, (/new,
/puzzle new, or /new puzzle), from an existing channel.

This should hopefully help people avoid forgetting to set the rounds
for a new puzzle.

Switch from using append() to update() for inserting into a spreadsheet

The append() method was the entirely wrong thing: It puts data in as
new rows below existing data. The update() method does what we want,
(sets data at a specific range).

Use a double dash separator for the m in the channel name of metapuzzles

The double dash is what will make the meta puzzles sort before all
non-metapuzzled.

Use consistent channel naming at puzzle creation time

We've had a bug for some time where the puzzle editing code would
construct a name for the puzzle channel based on hunt, and round, and
puzzle type, and puzzle_id but the puzzle creation code was only using
hunt and puzzle_id.

In this commit, we fix the puzzle creation code to use the same
puzzle_channel_name function so that channel names are created
consistently.

This commit also adds a check to reject a puzzle if it has the same
puzzle_id as an existing puzzle.

Add find_puzzle_for_puzzle_id

This exists so that the puzzle-creation code can ensure that it's not
creating a puzzle with the same puzzle_id as an existing
puzzle. Previously, Turbot was just relying on Slack to guarantee
uniqueness, (which worked when channel names were just made from
hunt_id and puzzle_id).

But more recently, the channel names have round names in them as
well. This set up a possible collision where two puzzle with the same
puzzle_id could be created but with different channel names, (if the
two puzzles were placed in different rounds). To be able to fix this
bug we need this query to be able to find a puzzle by means of using
the puzzle_id.

This does require a new index on the database, so that's here too,
(and we're nuking our database to be able to roll this out).

Fix comment string for find_puzzle_for_sort_key

The documentation here was stale and still referring to puzzle_id even
though this function is actually using sort_key, (which is similar but
is also slightly different).

Tighten up the welcome messages for a new hunt and a new puzzle

And point to `/help` in both cases for more details.

Expand list of pop-culture items to include video games

Perhaps bringing this list more up-to-date, (and also quite compatible
with the proclivities of ✈✈✈ Galactic Trendsetters ✈✈✈ who are writing
this year).

Drop names of specific people from the have-you-tried list

Replacing this list with "relevant team experts".

Fix `/help me` to not give a dispatch_failed error in a private channel

Since Turbot can't send a message to a private channel, instead we
just reply as an ephemeral message to the user.

Make "/help me" self-documenting

So that when people see others doing this, they will know how to do it too.

Implement a new "/help me" command that suggests something to try

Thanks to Acme for the original "Have you tried" list as obtained from:

    http://web.mit.edu/puzzle/www/resources.html

as:

    http://web.mit.edu/puzzle/www/resources/haveyoutried.pdf

Add an initial implementation of /help

So that Turbot can be self-documenting.

Update hunt welcome message to refer to `/puzzle new`

Previously it was pointing the users at `/puzzle` which is no longer
the correct command to use.

Fix call to find_hunt_for_hunt_id

It takes two parameters, not one, (was missing "turb" argument).

This should fix the edit_hunt button (the pencil) which was erroring
out while this bug was present.

Drop use of response_url in button handlers

Some buttons appear in a context, (like the app's "Home" view), where
there is no response_url, (we can't generate a message there). So we
can't rely on this. And we don't need to anyway, we can use the string
in the reteurn value to get an error message out to the user.

This commit should fix a bunch of broken puzzle edits button in the
Turbot "home" view.

Update TODO now that "/hunt edit" has been added

This closes out the last item we had as a required change prior to
Mystery Hunt 2021.

Make /edit command smart to auto-edit either puzzle or hunt

Depending on which kind of channel it is run in. It's still possible to
explicitly run `/edit puzzle` or `/edit hunt` instead.

Add a pencil-shaped "edit hunt" button when displaying a hunt

So that editing a hunt can be just as convenient as editing a puzzle.

Wire up "/edit hunt" to be the same as "/hunt edit"

Just as we did for "/edit" and "/edit puzzle" before.

Add a "/hunt edit" command

We expect this to be useful for a situation like Mystery Hunt where we
create the hunt and its channel in advance, invite all the users to
it, and then only later do we learn what the URL of the hunt actually
is.

Add "/new hunt" as a new sub-command of "/new"

This means we now have both "/hunt new" as well as "/new hunt" that
both do the same things. I'm not sure we'll want to keep both around
long-term, but they are both here now so that we can experiment and
see which feels more natural.

Update TOOD with two recently-completed items

There is a new "/hunt new" command now and puzzle sheets are now created
in a folder named after the hunt.

Create puzzle sheets in the hunt folder

This will be much nicer to keep our content organized within Google
drive. There will be one folder for each hunt rather than all the
various hunts' puzzles all mixed together at the root level.

Use the Google drive API to create a hunt's sheet within a folder

When a hunt is created, we create a folder in Google drive named
after the hunt_id and the create the hunt's sheet in that folder.

In future commits, we'll change the puzzle sheets to also be created
in this hunt's folder. This way, with all resources in one folder,
that folder can be shared out to members of the hunt, (this could
be used as an alternate access to hunt resources if Slack is not
available for any reason).

Rename identifier from item to hunt

The dynamodb API uses the generic term "item", but our code is more
clear with the more distinctive term "hunt" for the identifier here.

This commit has no functional change.

Implement "/hunt new" as a way to make a new hunt

This is more convenient than seeking out the Turbot app's Home tab.

Remove a line of dead code

A second return statement after an unconditional return statement
obviously cannot do anything.

Fix to work with old puzzles that don't have a type attribute

Without this, commands like /state and /puzzle on old puzzle just die.

Allow tag values to have numbers

There was unanimous consent that this could be useful, and it's an
easy change.

Add 4 new TODO items

Just the last few fixes we've identified we want to have in place
before the hunt next week.

Put the puzzle's name into the first tab of the sheet

Just to make it that much easier to tell apart multiple sheet windows
that a user might have to juggle.

Update the TODO list for a couple of recently-completed items

We got rid of that "Copy of" text in the sheet tabs, and we also put
the round name into the Slack channel.

Add both round and "-m" (for META), if appropriate, into channel name

For better grouping of related puzzles in the channel list

Use best-practice <@user_id> to mention a user in Slack

This way Slack expands this as a link to the user's full name.

Collapse link text inserted into sheets

Since we have functional links here we don't need to include the full
URL as part of the link text.

Rewrite all of sheets.py to look a little more like turbot code

The only actual intended behavioral change here is that the puzzle
sheet's now nuke the blank first sheet, (and instead have only sheets
copied over from the template).

Rename each sheet we copy from the template

To get rid of the silly "Copy of" text that we don't need.

Fix sheet creation to copy all sheets from our template

Nathan put a lot of word into this template sheet, so it was a shame
the sheets weren't all coming over. It turned out the only reason that
was the case is that the code has a hard-coded list of names of sheets
to copy, (and that, only because I haven't yet figured out the API for
enumerating sheets).

For now, just update the hardcoded list to match what's in the current
template.

Update TODO for recent addition of /tag command

This _almost_ completed the feature as intended. In fact, it went
further in one way in that it's already storing the tags in a field
that is separate from the state string. But it's falling short in that
the edit interface is not currently showing the tags at all.

Add hint to expand search terms if implicitly filtered

I keep accidentally missing some search results when testing because
I'm searching for a tag that only exists on a solved puzzle so something
like:

/hunt cryptic

is not finding the solved puzzle with the CRYTPIC tag due to the
implicit filtering to only unsolved puzzles.

I still want that implicit filtering, but maybe this nudge will be
helpful in cases like this.

Extend puzzle search to include type and tags

The matching on puzzle type means you can now do:

/hunt meta

or:

/hunt plain

to see all meta or non-meta puzzles.

And the matching on tags should be obvious.

Use a deep copy when comparing a puzzle to detect state modifications

Since the recent tags is an array, we need a deep copy of the puzzle dict
in order to be able to reliably compare the puzzle prior to the copy with
the one after the copy where a tag has been added or removed.

With this fix, adding or removing a tag now reliably updates the channel
description.

Add a /tag command to add or remove tags from puzzle

And put the tag values everywhere we have the state string already.

Add two new shortcut commands:

/new Which is the same as: /puzzle new
        /edit Which is the same as: /puzzle edit

I don't know if this is cleaner or messier, but I can at least put it
out there as an option.

For /puzzle on meta puzzles print all titles/answers of feeder puzzles

Where feeder puzzles are specifically defined as puzzle belonging to the
same round.

Put solution after puzzle name in /hunt reports

The concept here is to keep the puzzle names aligned to make it easier
to find a puzzle of interest in the sorted list.

Add a divider between rounds in the /hunt output

Just to make it a little easier to see the grouping of rounds.

TODO: Update for two recently-completed meta items

The punch list is getting short now...

Sort all meta puzzles before all non-meta puzzle in puzzle lists

This is in the output of /hunt, /round, and the Turbot home view.

new_puzzle_submission: Create a puzzle dict before shoving it into the DB

This will be handy for calling some puzzle.py functions that expect a dict.

Add a "meta" checkbox when creating/editing a puzzle

And display all meta puzzles with a bold "META" prefix.

Fix a typo in a comment

This comment was supposed to refer to puzzle_id, not hunt_id, which
made it confusing for me until I fixed it as in this commit.

Implement a /round command

This is much like the /hunt command with searching, etc. but with two
differences:

  1. It is limited to display puzzles in the same round(s) as the
     current puzzle

  2. It defaults to display all puzzles rather than unsolved puzzles
     like /hunt does

Implement a `/puzzle edit` command

As a simple shortcut rather than making the user type `/puzzle` and
then click the pencil icon.

Report change in a puzzle's solved status to the main hunt channel

We were already doing this from the /solved command but now we do it
for puzzle edits as well.

Put a message into the channel when a user edits a puzzle

So that other members of the puzzle are informed that something has changed.

Add display of round(s) in /puzzle output

Making the output more complete (while still remaining quite compact).

Add new /puzzle command which simply prints the current puzzle

This is the same format one could get from the /hunt command, but
limited to the current puzzle. This is a very convenient way to see
all the puzzle fields and to get access to the pencil button to edit
the current puzzle.

Rename puzzle creation command from "/puzzle" to "/puzzle new"

This is to create space for other commands later, (such as "/puzzle edit"
and a new status-reporting "/puzzle" command).

Don't re-set channel and sheet name or channel topic to the same value as before

The puzzle_update_channel_and_sheet function is modified here to
accept an old_puzzle argument in addition to the puzzle argument. By
using this it can decide whether there's any change in the sheet or
channel data before setting it.

This optimization avoids Slack reporting things like:

    Turbot renamed the channel from "hunt-puzzle" to "hunt-puzzle"

Which is obviously just noise.

Unify code to rename channel, set channel description, and rename sheet

With this code, all of those changes are made consistently regardless of
whether the change happens from /state, /solved, or a puzzle edit (which
could set status to either "solved" or "unsolved").