Skip to main content

aocd

This repo contains a CLI tool and library for creating and running Advent of Code solutions using Deno.

The CLI tool provides a way to configure authentication as your Advent of Code account and provides the ability to start a new project or day script from built-in templates.

The library is used within each day script that you write, and it manages fetching the problem input and running your solutions with the input. This allows you to avoid needing to manually download problem inputs and lets you avoid committing them into your repo.

Install

The aocd CLI tool can be installed with this command:

deno install -A -r -f https://deno.land/x/aocd/cli.ts

Usage

First you need to load your Advent of Code session cookie. You need to get this value from your browser after logging into Advent of Code.

aocd set-cookie COOKIE_VALUE_HERE

Next, you can use aocd to start a new project from a template. Run this command in a brand new directory with the correct year:

aocd init 2022

(If you already have an existing project that you want to start using aocd within, run the command aocd init --only-aocd-config YEAR instead. This will only create a “.aocdrc.json” file with the current year so that the aocd start DAY command works later.)

This will set up a Deno project within the current directory suitable for using with aocd. The project will include a file named “day_1.ts” which contains a basic example of using the aocd library:

import { assertEquals } from "https://deno.land/std@0.167.0/testing/asserts.ts";
import { runPart } from "https://deno.land/x/aocd/mod.ts";

function parse(input: string) {
  return input.trimEnd().split("\n").map(Number);
}

function part1(input: string): number {
  const items = parse(input);
  throw new Error("TODO");
}

// function part2(input: string): number {
//   const items = parse(input);
//   throw new Error("TODO");
// }

if (import.meta.main) {
  runPart(2022, 1, 1, part1);
  // runPart(2022, 1, 2, part2);
}

const TEST_INPUT = `\
6
7
8
9
10
`;

Deno.test("part1", () => {
  assertEquals(part1(TEST_INPUT), 11);
});

// Deno.test("part2", () => {
//   assertEquals(part2(TEST_INPUT), 12);
// });

You are expected to complete the parse(), part1(), and part2() functions. The parse() function defined in the template works fine for inputs that contain lines with one number each, but you must adjust the code for other types of input.

You are also able to have tests within the script. You are expected to replace the TEST_INPUT contents with test input from the Advent of Code problem description and then update the expected answers (11 and 12 in the Deno.test blocks) to the expected answers given in the problem description. There is no specific structure on tests that this library requires; you may want to add more test inputs and tests if the problem description gives multiple examples.

The if (import.meta.main) { check around the runPart() calls is so that the solutions are not run when tests are run. You are not expected to modify that if-block or its contents except to uncomment the part2() function, its runPart() call, and its test once you’re ready to work on part 2’s solution.

An example of a complete solution based on this template using this library can be seen at Macil/deno-advent2021/day_1.ts.

You can run a solution script like this:

deno run -A day_1.ts

You can run one day’s tests with deno test day_1.ts or by clicking the play button next to it inside of Visual Studio Code. You can run all days’ tests with deno task test.

You can debug a script within Visual Studio Code by picking Run -> Start Debugging in the toolbar while the script is open, or you can debug a script by running deno run -A --inspect-brk day_1.ts and then opening chrome://inspect in Chrome.

When you’re confident about a solution, you can add the --submit (or -s) flag to submit the solution and see if it was correct:

deno run -A day_1.ts --submit

When you’re ready to start a new solution script for another day’s challenge, run:

aocd start 2

This will create a day_2.ts file in the directory.

Advanced

Help Info

You can run aocd -h to see a listing of all subcommands and options it supports. Some subcommands have their own options which can be viewed by passing the -h flag to the subcommand, like aocd init -h.

Session and Cache Info

Aocd caches inputs so that they do not have to be refetched from the Advent of Code website every time a solution script is executed. Submitted answers are cached similarly. This cache and the session cookie can be erased by running aocd clear-data.

Aocd stores data inside cacheDir /aocd and dataDir /aocd on your computer within your user’s profile directory.

Safe Run

This library in normal use requires access to environment variables, read and write access to several directories, and network access, so using deno run with the -A (--allow-all) flag is recommended.

If you want to run a solution script in a sandbox that gives it no extra permissions, then you can use this command:

aocd safe-run day_1.ts

This causes day_1.ts to be executed by Deno with no permissions except for a communications channel to the privileged aocd process which it uses to fetch problem inputs using aocd’s session cookie and cache.

This command may be useful if you are trying out another person’s solutions and want to sandbox their code to be sure it doesn’t access any of your personal files. You can pass a remote URL to safe-run, such as a GitHub file’s raw link:

aocd safe-run https://raw.githubusercontent.com/Macil/deno-advent2021/main/day_1.ts

If you must pass in extra flags to the Deno process started by safe-run, you can do that with the --deno-flags parameter:

aocd safe-run --deno-flags="--allow-net --allow-env --reload" https://raw.githubusercontent.com/Macil/deno-advent2021/main/day_1.ts

This project is partly inspired by aocf and aocrunner which were made by other people for programming ecosystems other than Deno.