sharpmas

Advent of Code tooling in C#. Downloads your puzzle inputs, runs your solutions, checks the answers against an independent solver, and submits them for stars.

No solutions ship with it. Clone it, add your .env, and write your first day. Scotty's own solutions live on the scadoshi branch if you want worked examples.

Quick start

1. Add your session cookie. Log in at adventofcode.com, copy the value of the cookie named session from your browser's dev tools, then:

cp .env.template .env    # paste the cookie into COOKIE=

Only COOKIE is required, and it is 128 hex characters, checked on startup so a half-copied one says so. CONTACT and REPO_URL shape the User-Agent, since the site asks automated clients to be reachable.

2. Run something. One binary, one subcommand per mode, and the -- matters: without it dotnet run eats the flags as its own.

alias sharpmas='dotnet run --project src/Sharpmas.Cli --'

sharpmas fetch -y 2015 -d 1              # download one puzzle into cache/
sharpmas solve -y 2015 -d 1              # run your solution offline
sharpmas solve -y 2015 -d 1 --validate   # check answers against the solver
sharpmas solve -y 2015 -d 1 --submit     # check, then send for stars

-y and -d are filters: omit either for all of them. --submit validates first and only sends what the solver agrees with, because wrong answers cost an escalating cooldown. Unfiltered submits ask before posting everything; --yes skips that.

3. Write a day. Say 2015 day 1. Copy the template, which is compiled on every build and so cannot drift:

cp -r src/Sharpmas/Domain/Solution/YearTemplate src/Sharpmas/Domain/Solution/Year2015

Fix the namespace in the copied Day01/Puzzle.cs to match the path:

namespace Sharpmas.Domain.Solution.Year2015.Day01;

Write the parts. Parse runs once and throws on bad input; each part returns Answer.Solved(value), Answer.Visual(art), or Answer.None():

public Answer PartOne() => Answer.Solved(Input.Length.ToString());

Register it in Solvers in src/Sharpmas/Inbound/Solve/SolveRun.cs:

[(2015, 1)] = Outbound.Client.Solver.Solve<Domain.Solution.Year2015.Day01.Puzzle>,

That dictionary is the only list of what has been solved. Then:

sharpmas solve -y 2015 -d 1 --validate

Reading the output

year 2015 day 1 in 950.7µs (35.5µs parsing)
  part one: 138 (correct) [530.9µs]
  part two: 1771 (correct) [384.3µs]

One line per part: the answer, what is known about it, and how long it took. Timings never include the network.

Note	Meaning
nothing	Solved offline, unchecked
correct	The solver agrees
high, low, incorrect	The solver disagrees, so nothing was submitted
new star	Advent of Code just accepted it
starred	Advent of Code says the part was already solved
not logged in	The session cookie is missing or expired, so nothing was graded
unsupported	The solver has no implementation for this puzzle
rate limited, 1m 0s left to wait	Advent of Code refused to grade
(none)	The part has no answer, such as day 25 part two
(unwritten)	Nobody has written this part yet
error: ...	The part failed. The other part still ran

A run covering more than one day ends with where the time went:

total time spent parsing: 687.8µs
average parse time per day: 343.9µs
total time spent solving: 2.5695ms
average solve time per part: 642.4µs
slowest part: year 2016 day 1 part two [776.3µs]

One day gets none of it, since every line would restate the line above it.

Worth knowing

• Re-running fetch is safe: inputs are never re-downloaded, and a day still waiting on part two is rechecked until it unlocks.
• With no cookie set, solve works entirely offline from the cache, and --validate still works, since the solver needs no account.
• Shared helpers more than one day needs go in Domain/Solution/Common/.
• Debug builds are slow on brute-force days; dotnet run --project src/Sharpmas.Cli -c Release -- solve ... when it drags.

Going deeper

context/ holds the facts about the repo, one file per topic:

• context/architecture.md, the layout, how a solve runs, and the cache on disk.
• context/services.md, the two services and the etiquette the tool follows.
• context/design.md, every design decision in a line or two each.

rustmas is the original this rebuilds; its context/design/ and references.md carry the full reasoning and the service contracts as verified.

License

MIT. See LICENSE.