oscillation-cli 1.0.0

package/README.md

@@ -0,0 +1,44 @@
+# oscillation-cli
+
+Run your [Oscillation](https://tryoscillation.com) technical assessment from your terminal.
+
+```bash
+npm install -g oscillation-cli
+```
+
+## Usage
+
+Start your assessment. Run this in the folder where you want to work — **it starts your timer**, so only run it when you're ready.
+
+```bash
+oscillation init <assessment-id>
+```
+
+This downloads the project into a new folder, opens it in Cursor or VS Code, and starts the clock. Your assessment id is on your Oscillation dashboard.
+
+Check how much time you have left:
+
+```bash
+oscillation status
+```
+
+Submit your work, from anywhere inside the assessment folder:
+
+```bash
+oscillation submit
+```
+
+## Notes
+
+- Re-running `init` never resets your timer — the clock is kept on the server, and the original deadline stands.
+- `init` never overwrites an existing folder; it creates `sample-assessment-2`, `-3`, and so on.
+- If neither Cursor nor VS Code is found, the CLI prints the folder path for you to open yourself.
+
+## Configuration
+
+| Variable              | Default                      | Purpose                          |
+| --------------------- | ---------------------------- | -------------------------------- |
+| `OSCILLATION_API_URL` | `https://tryoscillation.com` | Point the CLI at another backend. |
+| `NO_COLOR`            | —                            | Disable colored output.           |
+
+Requires Node.js 20 or newer.

package/bin/oscillation.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { CliError } from "../src/api.js";
+import { init } from "../src/commands/init.js";
+import { status } from "../src/commands/status.js";
+import { submit } from "../src/commands/submit.js";
+import { bold, dim, red } from "../src/ui.js";
+
+const HELP = `
+${bold("oscillation")} — run your Oscillation assessment
+
+${bold("Commands")}
+  init <assessment-id>   Download the assessment and start your timer
+  status                 Show how much time you have left
+  submit                 Submit your work
+
+${dim("Run init in the folder where you want to work. Your timer starts then.")}
+`;
+
+const [command, ...args] = process.argv.slice(2);
+
+try {
+  switch (command) {
+    case "init":
+      await init(args[0]);
+      break;
+    case "status":
+      await status();
+      break;
+    case "submit":
+      await submit();
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      console.log(HELP);
+      break;
+    case "--version":
+    case "-v": {
+      const { default: pkg } = await import("../package.json", {
+        with: { type: "json" },
+      });
+      console.log(pkg.version);
+      break;
+    }
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+} catch (err) {
+  if (err instanceof CliError) {
+    console.error(`\n${red("✗")} ${err.message}\n`);
+    process.exit(1);
+  }
+  throw err;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "oscillation-cli",
+  "version": "1.0.0",
+  "description": "Run Oscillation technical assessments from your terminal.",
+  "type": "module",
+  "bin": {
+    "oscillation": "bin/oscillation.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "tar": "^7.5.20"
+  },
+  "keywords": [
+    "oscillation",
+    "assessment",
+    "hiring"
+  ],
+  "license": "MIT"
+}

package/src/api.js

@@ -0,0 +1,36 @@
+import { API_BASE } from "./config.js";
+
+/** Errors we print as a clean message rather than a stack trace. */
+export class CliError extends Error {}
+
+async function request(pathname, init) {
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/cli${pathname}`, init);
+  } catch {
+    throw new CliError(`Can't reach Oscillation at ${API_BASE}.`);
+  }
+
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    throw new CliError(body?.error ?? `Request failed (${res.status}).`);
+  }
+  return res;
+}
+
+export async function getInvite(id) {
+  return (await request(`/invites/${id}`)).json();
+}
+
+export async function startInvite(id) {
+  return (await request(`/invites/${id}/start`, { method: "POST" })).json();
+}
+
+export async function submitInvite(id) {
+  return (await request(`/invites/${id}/submit`, { method: "POST" })).json();
+}
+
+/** Web stream of the assessment project as .tar.gz. */
+export async function getBundle(id) {
+  return (await request(`/invites/${id}/bundle`)).body;
+}

package/src/commands/init.js

@@ -0,0 +1,98 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import * as tar from "tar";
+import { getBundle, getInvite, startInvite, CliError } from "../api.js";
+import { writeState } from "../config.js";
+import { openEditor } from "../editor.js";
+import { bold, dim, green, formatDeadline, formatDuration } from "../ui.js";
+
+/** "Sample Assessment" -> "sample-assessment" */
+function slugify(title) {
+  return (
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "") || "assessment"
+  );
+}
+
+/** Never clobber an existing folder: sample-assessment, -2, -3, ... */
+async function availableDir(base) {
+  for (let n = 1; ; n++) {
+    const dir = n === 1 ? base : `${base}-${n}`;
+    try {
+      await fs.access(dir);
+    } catch {
+      return dir;
+    }
+  }
+}
+
+export async function init(id) {
+  if (!id) {
+    throw new CliError(
+      "Usage: oscillation init <assessment-id>\n" +
+        "Find your assessment id on your Oscillation dashboard.",
+    );
+  }
+
+  const invite = await getInvite(id);
+
+  if (invite.status === "SUBMITTED") {
+    throw new CliError("You've already submitted this assessment.");
+  }
+  if (invite.status === "EXPIRED") {
+    throw new CliError("This assessment has expired.");
+  }
+
+  const { assessment } = invite;
+  console.log(`\n${bold(assessment.title)} ${dim("·")} ${assessment.company}`);
+  if (assessment.description) console.log(dim(assessment.description));
+
+  const dir = path.resolve(await availableDir(slugify(assessment.title)));
+
+  // Download and unpack first, then start the clock — a slow network shouldn't
+  // eat into the candidate's time.
+  console.log(dim("\nDownloading assessment..."));
+  await fs.mkdir(dir, { recursive: true });
+  const bundle = await getBundle(id);
+  await pipeline(Readable.fromWeb(bundle), tar.extract({ cwd: dir }));
+
+  // INVITED means this call starts the clock; STARTED means it was already
+  // running and the server kept the original deadline.
+  const resuming = invite.status === "STARTED";
+  const started = await startInvite(id);
+  await writeState(dir, {
+    inviteId: id,
+    title: assessment.title,
+    company: assessment.company,
+    startedAt: started.startedAt,
+    deadline: started.deadline,
+  });
+
+  console.log(
+    `${green("✓")} Ready in ${bold(path.relative(process.cwd(), dir) || ".")}`,
+  );
+
+  const editor = await openEditor(dir);
+  console.log(
+    editor
+      ? `${green("✓")} Opening in ${editor}...`
+      : dim(`  Open this folder in your editor: ${dir}`),
+  );
+
+  console.log(
+    `\n${bold(
+      resuming ? "⏱  Your timer is already running." : "⏱  Your timer has started.",
+    )} ` +
+      `${formatDuration(started.secondsRemaining)} remaining ` +
+      dim(`(due by ${formatDeadline(started.deadline)})`),
+  );
+  console.log(dim("   Read README.md for the task."));
+  console.log(
+    `\n   Check the clock:  ${bold("oscillation status")}\n` +
+      `   When you're done: ${bold("oscillation submit")}\n`,
+  );
+}

package/src/commands/status.js

@@ -0,0 +1,32 @@
+import { getInvite, CliError } from "../api.js";
+import { findState } from "../config.js";
+import { bold, dim, green, yellow, formatDeadline, formatDuration } from "../ui.js";
+
+export async function status() {
+  const found = await findState();
+  if (!found) {
+    throw new CliError(
+      "No assessment found here.\n" +
+        "Run this from inside your assessment folder (the one `oscillation init` created).",
+    );
+  }
+
+  // Ask the server rather than trusting the local clock — it's the timer of record.
+  const invite = await getInvite(found.state.inviteId);
+  console.log(
+    `\n${bold(invite.assessment.title)} ${dim("·")} ${invite.assessment.company}`,
+  );
+
+  if (invite.status === "SUBMITTED") {
+    console.log(`${green("✓")} Submitted.\n`);
+    return;
+  }
+
+  console.log(
+    invite.secondsRemaining > 0
+      ? `⏱  ${bold(formatDuration(invite.secondsRemaining))} remaining ` +
+          dim(`(due by ${formatDeadline(invite.deadline)})`)
+      : yellow("⏱  Time is up — submit as soon as you can."),
+  );
+  console.log(dim(`   Submit with: oscillation submit\n`));
+}

package/src/commands/submit.js

@@ -0,0 +1,47 @@
+import { createInterface } from "node:readline/promises";
+import { submitInvite, CliError } from "../api.js";
+import { findState } from "../config.js";
+import { bold, dim, green, yellow, formatDuration } from "../ui.js";
+
+async function confirm(question) {
+  // Non-interactive (CI, piped input): don't hang waiting on a prompt.
+  if (!process.stdin.isTTY) return true;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${question} ${dim("(y/N)")} `);
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function submit() {
+  const found = await findState();
+  if (!found) {
+    throw new CliError(
+      "No assessment found here.\n" +
+        "Run this from inside your assessment folder (the one `oscillation init` created).",
+    );
+  }
+
+  const { state } = found;
+  console.log(`\n${bold(state.title)} ${dim("·")} ${state.company}`);
+
+  const remaining = Math.max(
+    0,
+    Math.floor((new Date(state.deadline) - Date.now()) / 1000),
+  );
+  console.log(
+    remaining > 0
+      ? dim(`${formatDuration(remaining)} still on the clock.`)
+      : yellow("Your time is already up — this will submit late."),
+  );
+
+  if (!(await confirm("\nSubmit your work? This can't be undone."))) {
+    console.log(dim("Cancelled — nothing was submitted.\n"));
+    return;
+  }
+
+  await submitInvite(state.inviteId);
+  console.log(`\n${green("✓")} Submitted. ${dim("Thanks — you're all done.")}\n`);
+}

package/src/config.js

@@ -0,0 +1,34 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/** Points at the deployed app; overridable for local development. */
+export const API_BASE =
+  process.env.OSCILLATION_API_URL ?? "https://tryoscillation.com";
+
+/**
+ * Written into the assessment folder by `init` so `submit` knows which invite
+ * it belongs to without the candidate pasting the uuid again.
+ */
+export const STATE_FILE = ".oscillation.json";
+
+export async function writeState(dir, state) {
+  await fs.writeFile(
+    path.join(dir, STATE_FILE),
+    JSON.stringify(state, null, 2) + "\n",
+  );
+}
+
+/** Walks up from cwd so `submit` works from anywhere inside the project. */
+export async function findState(from = process.cwd()) {
+  let dir = path.resolve(from);
+  while (true) {
+    try {
+      const raw = await fs.readFile(path.join(dir, STATE_FILE), "utf8");
+      return { dir, state: JSON.parse(raw) };
+    } catch {
+      const parent = path.dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  }
+}

package/src/editor.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+
+// Cursor first, then VS Code — matching the editors the assessment flow assumes.
+const EDITORS = [
+  {
+    name: "Cursor",
+    cmd: "cursor",
+    // The CLI launcher inside the app bundle, for the common case where the
+    // user never ran "Install 'cursor' command in PATH".
+    mac: "/Applications/Cursor.app/Contents/Resources/app/bin/code",
+    app: "Cursor",
+  },
+  {
+    name: "VS Code",
+    cmd: "code",
+    mac: "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
+    app: "Visual Studio Code",
+  },
+];
+
+/**
+ * Spawns without a shell — the candidate's path may contain spaces or shell
+ * metacharacters, and shell args are concatenated rather than escaped.
+ * Windows launchers are `.cmd` shims, so cmd.exe is invoked directly there
+ * with the path kept as its own argument.
+ */
+function trySpawn(cmd, args) {
+  return new Promise((resolve) => {
+    const child =
+      process.platform === "win32"
+        ? spawn("cmd.exe", ["/c", cmd, ...args], {
+            stdio: "ignore",
+            detached: true,
+          })
+        : spawn(cmd, args, { stdio: "ignore", detached: true });
+
+    child.on("error", () => resolve(false));
+    child.on("spawn", () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+}
+
+/**
+ * Opens the assessment folder in the first editor we can find. Returns the
+ * editor name, or null if none is installed — never throws, since failing to
+ * open an editor must not fail `init`.
+ */
+export async function openEditor(dir) {
+  for (const editor of EDITORS) {
+    const candidates = [
+      // On PATH (works when the user installed the shell command).
+      process.platform === "win32" ? `${editor.cmd}.cmd` : editor.cmd,
+      // The launcher inside the macOS app bundle.
+      ...(process.platform === "darwin" ? [editor.mac] : []),
+    ];
+
+    for (const cmd of candidates) {
+      if (await trySpawn(cmd, [dir])) return editor.name;
+    }
+
+    // Last resort on macOS: hand the folder to LaunchServices, which finds the
+    // app wherever it's installed.
+    if (
+      process.platform === "darwin" &&
+      (await trySpawnOpen(editor.app, dir))
+    ) {
+      return editor.name;
+    }
+  }
+  return null;
+}
+
+/**
+ * `open -a` exits non-zero when the app isn't installed, so unlike the spawns
+ * above we have to wait for the exit code rather than trust a successful spawn.
+ */
+function trySpawnOpen(appName, dir) {
+  return new Promise((resolve) => {
+    const child = spawn("open", ["-a", appName, dir], { stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+}

package/src/ui.js

@@ -0,0 +1,23 @@
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+
+export const bold = wrap("1");
+export const dim = wrap("2");
+export const green = wrap("32");
+export const yellow = wrap("33");
+export const red = wrap("31");
+
+export function formatDuration(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  if (h === 0) return `${m}m`;
+  return m === 0 ? `${h}h` : `${h}h ${m}m`;
+}
+
+/** Local wall-clock time, so "due by" matches the candidate's own clock. */
+export function formatDeadline(iso) {
+  return new Date(iso).toLocaleTimeString([], {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}