litmus-cli 0.2.0

package/src/index.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { program } from "commander"
+import { runInit } from "./commands/init.js"
+import { runSubmit } from "./commands/submit.js"
+
+const VERSION = "0.1.0"
+
+program
+  .name("litmus")
+  .description("Litmus engineering assessment CLI")
+  .version(VERSION)
+
+program
+  .command("init <token>")
+  .description("Download and set up a Litmus assessment")
+  .action(async (token: string) => {
+    try {
+      await runInit(token)
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exit(1)
+    }
+  })
+
+program
+  .command("submit")
+  .description("Submit your completed assessment")
+  .option("-y, --yes", "Skip confirmation prompt")
+  .action(async (opts: { yes?: boolean }) => {
+    try {
+      await runSubmit(opts)
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exit(1)
+    }
+  })
+
+program.parse()

package/src/lib/api.ts

@@ -0,0 +1,93 @@
+import FormData from "form-data"
+import { createReadStream } from "fs"
+
+export interface InitMetadata {
+  assessmentId: string
+  assessmentName: string
+  folderName: string
+  candidateEmail: string
+  candidateName: string
+  deadline: string | null
+  timeLimit: number | null
+  startedAt: string
+}
+
+export interface SubmitResult {
+  success: boolean
+  submissionId: string
+  message: string
+}
+
+/**
+ * Fetch assessment metadata by token.
+ * Marks the candidate as in_progress if they were pending.
+ */
+export async function fetchInitMetadata(
+  apiBase: string,
+  token: string
+): Promise<InitMetadata> {
+  const url = `${apiBase}/api/cli/init?token=${encodeURIComponent(token)}`
+  const res = await fetch(url)
+  const body = await res.json().catch(() => ({})) as Record<string, unknown>
+
+  if (!res.ok) {
+    const message = (body.message as string) || (body.error as string) || `Server returned ${res.status}`
+    throw new Error(message)
+  }
+
+  return body as unknown as InitMetadata
+}
+
+/**
+ * Download the candidate ZIP by token.
+ * Returns a ReadableStream of the ZIP bytes.
+ */
+export async function downloadZip(
+  apiBase: string,
+  token: string
+): Promise<Response> {
+  const url = `${apiBase}/api/cli/download?token=${encodeURIComponent(token)}`
+  const res = await fetch(url)
+
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({})) as Record<string, unknown>
+    const message = (body.message as string) || (body.error as string) || `Server returned ${res.status}`
+    throw new Error(message)
+  }
+
+  return res
+}
+
+/**
+ * Upload a ZIP file for submission.
+ */
+export async function submitZip(
+  apiBase: string,
+  token: string,
+  zipPath: string,
+  fileName: string
+): Promise<SubmitResult> {
+  const url = `${apiBase}/api/cli/submit?token=${encodeURIComponent(token)}`
+
+  const form = new FormData()
+  form.append("file", createReadStream(zipPath), {
+    filename: fileName,
+    contentType: "application/zip",
+  })
+
+  const res = await fetch(url, {
+    method: "POST",
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    body: form as any,
+    headers: form.getHeaders(),
+  })
+
+  const body = await res.json().catch(() => ({})) as Record<string, unknown>
+
+  if (!res.ok) {
+    const message = (body.message as string) || (body.error as string) || `Server returned ${res.status}`
+    throw new Error(message)
+  }
+
+  return body as unknown as SubmitResult
+}

package/src/lib/config.ts

@@ -0,0 +1,59 @@
+import { readFile, writeFile, mkdir } from "fs/promises"
+import { existsSync } from "fs"
+import path from "path"
+
+export interface LitmusConfig {
+  assessmentId: string
+  assessmentName: string
+  candidateEmail: string
+  candidateName: string
+  token: string
+  startedAt: string
+  deadline: string | null
+  timeLimit: number | null // minutes
+  apiBase: string
+}
+
+const CONFIG_DIR = ".litmus"
+const CONFIG_FILE = "config.json"
+
+export function getConfigPath(projectRoot: string): string {
+  return path.join(projectRoot, CONFIG_DIR, CONFIG_FILE)
+}
+
+export async function writeConfig(
+  projectRoot: string,
+  config: LitmusConfig
+): Promise<void> {
+  const configDir = path.join(projectRoot, CONFIG_DIR)
+  await mkdir(configDir, { recursive: true })
+  const configPath = path.join(configDir, CONFIG_FILE)
+  await writeFile(configPath, JSON.stringify(config, null, 2), "utf8")
+}
+
+/**
+ * Read .litmus/config.json from the current directory or a parent directory.
+ * Returns null if no config is found.
+ */
+export async function readConfig(): Promise<LitmusConfig | null> {
+  let dir = process.cwd()
+
+  // Walk up the directory tree looking for .litmus/config.json
+  while (true) {
+    const configPath = path.join(dir, CONFIG_DIR, CONFIG_FILE)
+    if (existsSync(configPath)) {
+      try {
+        const raw = await readFile(configPath, "utf8")
+        return JSON.parse(raw) as LitmusConfig
+      } catch {
+        return null
+      }
+    }
+
+    const parent = path.dirname(dir)
+    if (parent === dir) break // Reached filesystem root
+    dir = parent
+  }
+
+  return null
+}

package/src/lib/extract.ts

@@ -0,0 +1,15 @@
+import { mkdir } from "fs/promises"
+import unzipper from "unzipper"
+
+/**
+ * Extract a ZIP file from disk to a target directory.
+ * Using Open.file + extract() is the most reliable unzipper API.
+ */
+export async function extractZip(
+  zipPath: string,
+  targetDir: string
+): Promise<void> {
+  await mkdir(targetDir, { recursive: true })
+  const directory = await unzipper.Open.file(zipPath)
+  await directory.extract({ path: targetDir })
+}

package/src/lib/tracker.ts

@@ -0,0 +1,38 @@
+import { spawn } from "child_process"
+import { mkdirSync, writeFileSync } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Start the chokidar file watcher in the background.
+ * Spawns dist/watcher.cjs as a detached process; logs file events to
+ * <projectDir>/.litmus/activity.jsonl for later inclusion in the submission ZIP.
+ */
+export function startTracker(projectDir: string): void {
+  const litmusDir = path.join(projectDir, ".litmus")
+  const activityLog = path.join(litmusDir, "activity.jsonl")
+  const pidFile = path.join(litmusDir, "tracker.pid")
+  const watcherScript = path.join(__dirname, "watcher.cjs")
+
+  try {
+    mkdirSync(litmusDir, { recursive: true })
+  } catch {
+    // Non-critical
+  }
+
+  const child = spawn("node", [watcherScript, projectDir, activityLog], {
+    detached: true,
+    stdio: "ignore",
+  })
+
+  if (child.pid) {
+    child.unref()
+    try {
+      writeFileSync(pidFile, String(child.pid), "utf8")
+    } catch {
+      // Non-critical
+    }
+  }
+}

package/src/lib/watcher.cjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Litmus file activity watcher.
+ * Runs as a detached background process started by `litmus init`.
+ * Usage: node watcher.cjs <projectDir> <activityLogPath>
+ *
+ * Writes newline-delimited JSON to the activity log:
+ *   { "ts": "ISO-8601", "type": "add"|"change"|"unlink", "path": "relative/path" }
+ */
+
+const chokidar = require("chokidar")
+const fs = require("fs")
+const path = require("path")
+
+const [, , projectDir, activityLogPath] = process.argv
+
+if (!projectDir || !activityLogPath) {
+  process.stderr.write("Usage: node watcher.cjs <projectDir> <activityLogPath>\n")
+  process.exit(1)
+}
+
+// Ensure the log directory exists
+fs.mkdirSync(path.dirname(activityLogPath), { recursive: true })
+
+// Open the log file for appending
+const log = fs.createWriteStream(activityLogPath, { flags: "a" })
+
+function write(type, filePath) {
+  const event = JSON.stringify({
+    ts: new Date().toISOString(),
+    type,
+    path: path.relative(projectDir, filePath),
+  })
+  log.write(event + "\n")
+}
+
+const ignored = [
+  /(^|[/\\])\./,      // dotfiles and dotdirs (including .git, .litmus)
+  /node_modules/,
+  /__pycache__/,
+  /\.pyc$/,
+  /\.class$/,
+]
+
+chokidar
+  .watch(projectDir, {
+    ignored,
+    ignoreInitial: true,
+    persistent: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+  })
+  .on("add", (p) => write("add", p))
+  .on("change", (p) => write("change", p))
+  .on("unlink", (p) => write("unlink", p))
+  .on("error", (err) => {
+    // Log errors but don't crash — tracking is non-critical
+    process.stderr.write(`[watcher] error: ${err}\n`)
+  })

package/src/lib/zip.ts

@@ -0,0 +1,104 @@
+import archiver from "archiver"
+import { createWriteStream, readFileSync, existsSync } from "fs"
+import path from "path"
+import os from "os"
+
+// Directories always excluded from submissions.
+// NOTE: .git is intentionally NOT excluded — git history is included so the
+// analysis backend can run parse_git_history() on the submission.
+const ALWAYS_EXCLUDE = [
+  "node_modules",
+  "__pycache__",
+  "venv",
+  ".venv",
+  "env",
+  ".env",
+  "target",        // Rust/Java build output
+  "build",
+  "dist",
+  ".gradle",
+  ".idea",
+  ".DS_Store",
+  "*.pyc",
+  "*.class",
+  // Legacy injected tracking files — exclude so they don't pollute submissions
+  // from assessments downloaded before the CLI-native tracking was deployed.
+  "setup.sh",
+  "tracker.py",
+  "tracker.js",
+  "heartbeat.py",
+]
+
+/**
+ * Create a ZIP of the project directory for submission.
+ * Respects .gitignore patterns (basic support) and excludes common large dirs.
+ * Always includes .litmus/activity.jsonl (the tracking log).
+ *
+ * @param projectDir - Root of the project to zip
+ * @returns Path to the temporary ZIP file
+ */
+export async function createSubmissionZip(projectDir: string): Promise<string> {
+  const tmpFile = path.join(os.tmpdir(), `litmus-submission-${Date.now()}.zip`)
+  const output = createWriteStream(tmpFile)
+
+  const archive = archiver("zip", { zlib: { level: 6 } })
+
+  return new Promise((resolve, reject) => {
+    output.on("close", () => resolve(tmpFile))
+    archive.on("error", reject)
+    archive.pipe(output)
+
+    // Compute glob patterns to ignore
+    const ignoredGlobs = buildIgnoreGlobs(projectDir)
+
+    // Add the project directory contents (not the directory itself)
+    archive.glob("**/*", {
+      cwd: projectDir,
+      dot: true, // Include dotfiles like .litmus/
+      ignore: ignoredGlobs,
+    })
+
+    archive.finalize()
+  })
+}
+
+function buildIgnoreGlobs(projectDir: string): string[] {
+  const patterns: string[] = []
+
+  // Always-excluded dirs/patterns
+  for (const excluded of ALWAYS_EXCLUDE) {
+    if (excluded.startsWith("*")) {
+      patterns.push(excluded)
+    } else {
+      patterns.push(`${excluded}/**`)
+      patterns.push(`**/${excluded}/**`)
+    }
+  }
+
+  // Basic .gitignore support
+  const gitignorePath = path.join(projectDir, ".gitignore")
+  if (existsSync(gitignorePath)) {
+    try {
+      const lines = readFileSync(gitignorePath, "utf8")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith("#"))
+
+      for (const line of lines) {
+        if (line.endsWith("/")) {
+          // Directory pattern
+          const dir = line.slice(0, -1)
+          patterns.push(`${dir}/**`)
+          patterns.push(`**/${dir}/**`)
+        } else {
+          patterns.push(line)
+          patterns.push(`**/${line}`)
+        }
+      }
+    } catch {
+      // Ignore .gitignore parse errors
+    }
+  }
+
+  return patterns
+}

package/src/utils/detect-project.ts

@@ -0,0 +1,83 @@
+import { existsSync } from "fs"
+import path from "path"
+
+export type ProjectType =
+  | "node"
+  | "python"
+  | "go"
+  | "java"
+  | "dotnet"
+  | "rust"
+  | "ruby"
+  | "php"
+  | "unknown"
+
+export interface ProjectInfo {
+  type: ProjectType
+  installCommand: string | null
+  runHint: string | null
+}
+
+/**
+ * Detect project type and suggest an install command.
+ */
+export function detectProject(dir: string): ProjectInfo {
+  if (existsSync(path.join(dir, "package.json"))) {
+    const hasYarnLock = existsSync(path.join(dir, "yarn.lock"))
+    const hasPnpmLock = existsSync(path.join(dir, "pnpm-lock.yaml"))
+    const installCommand = hasPnpmLock
+      ? "pnpm install"
+      : hasYarnLock
+        ? "yarn"
+        : "npm install"
+    return { type: "node", installCommand, runHint: "npm start / npm test" }
+  }
+
+  if (
+    existsSync(path.join(dir, "requirements.txt")) ||
+    existsSync(path.join(dir, "pyproject.toml")) ||
+    existsSync(path.join(dir, "setup.py"))
+  ) {
+    // Create a venv and install into it (replaces what the old setup.sh did).
+    // Use venv/bin/pip directly so activation isn't required at install time.
+    const pipBin = process.platform === "win32" ? "venv\\Scripts\\pip" : "venv/bin/pip"
+    const installCommand = existsSync(path.join(dir, "requirements.txt"))
+      ? `python3 -m venv venv && ${pipBin} install -r requirements.txt`
+      : `python3 -m venv venv && ${pipBin} install -e .`
+    return {
+      type: "python",
+      installCommand,
+      runHint: "source venv/bin/activate  # then: python main.py / pytest",
+    }
+  }
+
+  if (existsSync(path.join(dir, "go.mod"))) {
+    return { type: "go", installCommand: "go mod download", runHint: "go run . / go test ./..." }
+  }
+
+  if (existsSync(path.join(dir, "pom.xml"))) {
+    return { type: "java", installCommand: "mvn install", runHint: "mvn test" }
+  }
+
+  if (existsSync(path.join(dir, "build.gradle")) || existsSync(path.join(dir, "build.gradle.kts"))) {
+    return { type: "java", installCommand: "gradle build", runHint: "gradle test" }
+  }
+
+  if (existsSync(path.join(dir, "*.csproj")) || existsSync(path.join(dir, "*.sln"))) {
+    return { type: "dotnet", installCommand: "dotnet restore", runHint: "dotnet run / dotnet test" }
+  }
+
+  if (existsSync(path.join(dir, "Cargo.toml"))) {
+    return { type: "rust", installCommand: null, runHint: "cargo run / cargo test" }
+  }
+
+  if (existsSync(path.join(dir, "Gemfile"))) {
+    return { type: "ruby", installCommand: "bundle install", runHint: "ruby main.rb / rspec" }
+  }
+
+  if (existsSync(path.join(dir, "composer.json"))) {
+    return { type: "php", installCommand: "composer install", runHint: "php -S localhost:8000" }
+  }
+
+  return { type: "unknown", installCommand: null, runHint: null }
+}

package/src/utils/errors.ts

@@ -0,0 +1,41 @@
+import chalk from "chalk"
+
+export const FALLBACK_URL = "https://app.litmus.sh"
+
+/**
+ * Print a plain-English error and exit.
+ * Always shows a fallback URL for candidates who can't resolve the issue.
+ */
+export function fatal(message: string, hint?: string): never {
+  console.error()
+  console.error(chalk.red("✗ Error: ") + message)
+  if (hint) {
+    console.error(chalk.dim("  Hint: ") + hint)
+  }
+  console.error(
+    chalk.dim(`  Need help? Visit ${FALLBACK_URL} to manage your assessment.`)
+  )
+  console.error()
+  process.exit(1)
+}
+
+/**
+ * Print a warning (non-fatal).
+ */
+export function warn(message: string): void {
+  console.warn(chalk.yellow("⚠ Warning: ") + message)
+}
+
+/**
+ * Print a success message.
+ */
+export function success(message: string): void {
+  console.log(chalk.green("✓ ") + message)
+}
+
+/**
+ * Print a plain info line.
+ */
+export function info(message: string): void {
+  console.log(chalk.dim("  ") + message)
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}