offcourse 0.0.2 → 1.0.0

package/src/cli/index.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { configGetCommand, configSetCommand, configShowCommand } from "./commands/config.js";
+import { inspectCommand } from "./commands/inspect.js";
+import { loginCommand, logoutCommand } from "./commands/login.js";
+import { statusCommand, statusListCommand, type StatusOptions } from "./commands/status.js";
+import { syncCommand, type SyncOptions } from "./commands/sync.js";
+import {
+  syncHighLevelCommand,
+  isHighLevelPortal,
+  type SyncHighLevelOptions,
+} from "./commands/syncHighLevel.js";
+
+const program = new Command();
+
+program
+  .name("offcourse")
+  .description("Download online courses for offline access – of course!")
+  .version("0.1.0");
+
+// Login command
+program
+  .command("login")
+  .description("Log in to a learning platform (opens browser)")
+  .option("-f, --force", "Force re-login even if session exists")
+  .action(loginCommand);
+
+// Logout command
+program.command("logout").description("Clear saved session").action(logoutCommand);
+
+// Sync command - auto-detects platform
+program
+  .command("sync <url>")
+  .description("Download a course for offline access (auto-detects platform)")
+  .option("--skip-videos", "Skip video downloads (only save text content)")
+  .option("--skip-content", "Skip text content (only download videos)")
+  .option("--dry-run", "Scan course structure without downloading")
+  .option("--limit <n>", "Limit to first N lessons (for testing)", parseInt)
+  .option("-f, --force", "Force full rescan of all lessons")
+  .option("--retry-failed", "Retry failed lessons with detailed diagnostics")
+  .option("--visible", "Show browser window (default: headless)")
+  .option("-q, --quality <quality>", "Preferred video quality (e.g., 720p, 1080p)")
+  .option("--course-name <name>", "Override detected course name")
+  .action((url: string, options: SyncOptions & SyncHighLevelOptions) => {
+    // Auto-detect platform
+    if (url.includes("skool.com")) {
+      return syncCommand(url, options);
+    } else if (isHighLevelPortal(url)) {
+      return syncHighLevelCommand(url, options);
+    } else {
+      // Default: try HighLevel (most generic)
+      console.log("Platform not recognized, trying as HighLevel portal...");
+      return syncHighLevelCommand(url, options);
+    }
+  });
+
+// Explicit Skool sync command
+program
+  .command("sync-skool <url>")
+  .description("Download a Skool course for offline access")
+  .option("--skip-videos", "Skip video downloads (only save text content)")
+  .option("--skip-content", "Skip text content (only download videos)")
+  .option("--dry-run", "Scan course structure without downloading")
+  .option("--limit <n>", "Limit to first N lessons (for testing)", parseInt)
+  .option("-f, --force", "Force full rescan of all lessons")
+  .option("--retry-failed", "Retry failed lessons with detailed diagnostics")
+  .option("--visible", "Show browser window (default: headless)")
+  .action(syncCommand);
+
+// Explicit HighLevel sync command
+program
+  .command("sync-highlevel <url>")
+  .description("Download a HighLevel (GoHighLevel) course for offline access")
+  .option("--skip-videos", "Skip video downloads (only save text content)")
+  .option("--skip-content", "Skip text content (only download videos)")
+  .option("--dry-run", "Scan course structure without downloading")
+  .option("--limit <n>", "Limit to first N lessons (for testing)", parseInt)
+  .option("--visible", "Show browser window (default: headless)")
+  .option("-q, --quality <quality>", "Preferred video quality (e.g., 720p, 1080p)")
+  .option("--course-name <name>", "Override detected course name")
+  .action(syncHighLevelCommand);
+
+// Status command
+program
+  .command("status [url]")
+  .description("Show sync status for a course (or list all if no URL)")
+  .option("--errors", "Show details for failed downloads")
+  .option("--pending", "Show not-yet-scanned lessons")
+  .option("-a, --all", "Show all details")
+  .action((url: string | undefined, options: StatusOptions) => {
+    if (url) {
+      statusCommand(url, options);
+    } else {
+      void statusListCommand();
+    }
+  });
+
+// Inspect command (debugging)
+program
+  .command("inspect <url>")
+  .description("Analyze page structure for debugging")
+  .option("-o, --output <dir>", "Save analysis to directory")
+  .option("--full", "Save complete HTML as well")
+  .option("--click", "Try to click video preview to trigger lazy loading")
+  .action(inspectCommand);
+
+// Config commands
+const configCmd = program.command("config").description("Manage configuration");
+
+configCmd.command("show").description("Show all configuration values").action(configShowCommand);
+
+configCmd.command("get <key>").description("Get a configuration value").action(configGetCommand);
+
+configCmd
+  .command("set <key> <value>")
+  .description("Set a configuration value")
+  .action(configSetCommand);
+
+// Parse and run
+program.parse();

package/src/config/configManager.ts

@@ -0,0 +1,75 @@
+/**
+ * Application configuration using the `conf` package.
+ * Excluded from coverage - testing would just test the conf package.
+ */
+import Conf from "conf";
+import { APP_DIR, SESSIONS_DIR } from "./paths.js";
+import { Config, configSchema } from "./schema.js";
+import { ensureDir } from "../shared/fs.js";
+
+/**
+ * Application configuration store using conf package.
+ * Provides atomic writes, dot-notation access, and safe defaults.
+ */
+const store = new Conf<Config>({
+  projectName: "offcourse",
+  cwd: APP_DIR,
+  configName: "config",
+  defaults: configSchema.parse({}),
+});
+
+/**
+ * Ensures all required application directories exist.
+ */
+export async function ensureAppDirectories(): Promise<void> {
+  const dirs = [APP_DIR, SESSIONS_DIR, `${APP_DIR}/sync-state`];
+  await Promise.all(dirs.map((dir) => ensureDir(dir)));
+}
+
+/**
+ * Loads the application configuration.
+ * Returns validated config with defaults applied.
+ */
+export function loadConfig(): Config {
+  // Validate with zod to ensure type safety
+  return configSchema.parse(store.store);
+}
+
+/**
+ * Saves the configuration.
+ */
+export function saveConfig(config: Config): void {
+  const validated = configSchema.parse(config);
+  store.store = validated;
+}
+
+/**
+ * Updates specific config values.
+ */
+export function updateConfig(updates: Partial<Config>): Config {
+  const current = loadConfig();
+  const updated = configSchema.parse({ ...current, ...updates });
+  store.store = updated;
+  return updated;
+}
+
+/**
+ * Gets a specific config value.
+ */
+export function getConfigValue<K extends keyof Config>(key: K): Config[K] {
+  return store.get(key);
+}
+
+/**
+ * Clears all configuration (for testing or reset).
+ */
+export function clearConfig(): void {
+  store.clear();
+}
+
+/**
+ * Gets the path to the config file.
+ */
+export function getConfigPath(): string {
+  return store.path;
+}

package/src/config/paths.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { expandPath, getSessionPath, getSyncStatePath, APP_DIR } from "./paths.js";
+
+describe("expandPath", () => {
+  it("expands ~ to home directory", () => {
+    const result = expandPath("~/Downloads/offcourse");
+    expect(result).toBe(join(homedir(), "Downloads/offcourse"));
+  });
+
+  it("expands ~/nested/path correctly", () => {
+    const result = expandPath("~/foo/bar/baz");
+    expect(result).toBe(join(homedir(), "foo/bar/baz"));
+  });
+
+  it("returns absolute paths unchanged", () => {
+    const result = expandPath("/usr/local/bin");
+    expect(result).toBe("/usr/local/bin");
+  });
+
+  it("returns relative paths unchanged", () => {
+    const result = expandPath("relative/path");
+    expect(result).toBe("relative/path");
+  });
+
+  it("handles just ~ correctly", () => {
+    // untildify expands ~ to home directory
+    const result = expandPath("~");
+    expect(result).toBe(homedir());
+  });
+
+  it("handles empty string", () => {
+    const result = expandPath("");
+    expect(result).toBe("");
+  });
+});
+
+describe("getSessionPath", () => {
+  it("generates correct session path for simple domain", () => {
+    const result = getSessionPath("example.com");
+    expect(result).toMatch(/\.offcourse\/sessions\/example\.com\.json$/);
+  });
+
+  it("sanitizes domains with special characters", () => {
+    const result = getSessionPath("sub.domain.com");
+    expect(result).toMatch(/sub\.domain\.com\.json$/);
+  });
+
+  it("replaces invalid filesystem characters with underscores", () => {
+    const result = getSessionPath("example.com/path?query");
+    expect(result).toMatch(/example\.com_path_query\.json$/);
+  });
+
+  it("handles domains with ports", () => {
+    const result = getSessionPath("localhost:3000");
+    expect(result).toMatch(/localhost_3000\.json$/);
+  });
+});
+
+describe("getSyncStatePath", () => {
+  it("generates correct sync state path for simple slug", () => {
+    const result = getSyncStatePath("my-course");
+    expect(result).toMatch(/\.offcourse\/sync-state\/my-course\.json$/);
+  });
+
+  it("sanitizes slugs with special characters", () => {
+    const result = getSyncStatePath("Course Name: Special!");
+    expect(result).toMatch(/Course_Name__Special_\.json$/);
+  });
+
+  it("handles slugs with only valid characters", () => {
+    const result = getSyncStatePath("valid-slug-123");
+    expect(result).toMatch(/valid-slug-123\.json$/);
+  });
+});
+
+describe("APP_DIR", () => {
+  it("is defined and contains offcourse", () => {
+    expect(APP_DIR).toBeDefined();
+    expect(APP_DIR).toContain("offcourse");
+  });
+});

package/src/config/paths.ts

@@ -0,0 +1,36 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import untildify from "untildify";
+
+/**
+ * Application directory paths.
+ * Uses ~/.offcourse/ for easy access and visibility.
+ */
+export const APP_DIR = join(homedir(), ".offcourse");
+export const SESSIONS_DIR = join(APP_DIR, "sessions");
+export const CONFIG_FILE = join(APP_DIR, "config.json");
+export const CACHE_DIR = join(APP_DIR, "cache");
+
+/**
+ * Get the session file path for a specific domain.
+ */
+export function getSessionPath(domain: string): string {
+  // Sanitize domain for filesystem
+  const safeDomain = domain.replace(/[^a-zA-Z0-9.-]/g, "_");
+  return join(SESSIONS_DIR, `${safeDomain}.json`);
+}
+
+/**
+ * Get the sync state file path for a course.
+ */
+export function getSyncStatePath(courseSlug: string): string {
+  const safeSlug = courseSlug.replace(/[^a-zA-Z0-9-]/g, "_");
+  return join(APP_DIR, "sync-state", `${safeSlug}.json`);
+}
+
+/**
+ * Expand ~ to home directory in paths.
+ */
+export function expandPath(path: string): string {
+  return untildify(path);
+}

package/src/config/schema.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from "vitest";
+import { configSchema, courseSyncStateSchema, sessionInfoSchema } from "./schema.js";
+
+describe("configSchema", () => {
+  it("parses empty object with defaults", () => {
+    const result = configSchema.parse({});
+    expect(result).toEqual({
+      outputDir: "~/Downloads/offcourse",
+      videoQuality: "highest",
+      concurrency: 2,
+      retryAttempts: 3,
+      headless: true,
+    });
+  });
+
+  it("accepts valid config values", () => {
+    const input = {
+      outputDir: "/custom/path",
+      videoQuality: "720p" as const,
+      concurrency: 4,
+      retryAttempts: 5,
+      headless: false,
+    };
+    const result = configSchema.parse(input);
+    expect(result).toEqual(input);
+  });
+
+  it("rejects invalid video quality", () => {
+    expect(() => configSchema.parse({ videoQuality: "4k" })).toThrow();
+  });
+
+  it("rejects concurrency outside valid range", () => {
+    expect(() => configSchema.parse({ concurrency: 0 })).toThrow();
+    expect(() => configSchema.parse({ concurrency: 6 })).toThrow();
+  });
+
+  it("rejects retry attempts outside valid range", () => {
+    expect(() => configSchema.parse({ retryAttempts: -1 })).toThrow();
+    expect(() => configSchema.parse({ retryAttempts: 11 })).toThrow();
+  });
+
+  it("accepts all valid video quality values", () => {
+    const qualities = ["highest", "lowest", "1080p", "720p", "480p"] as const;
+    for (const quality of qualities) {
+      const result = configSchema.parse({ videoQuality: quality });
+      expect(result.videoQuality).toBe(quality);
+    }
+  });
+});
+
+describe("courseSyncStateSchema", () => {
+  it("validates minimal course sync state", () => {
+    const input = {
+      url: "https://example.com/course",
+      name: "My Course",
+      modules: [],
+    };
+    const result = courseSyncStateSchema.parse(input);
+    expect(result.url).toBe(input.url);
+    expect(result.name).toBe(input.name);
+    expect(result.modules).toEqual([]);
+  });
+
+  it("validates complete course sync state", () => {
+    const input = {
+      url: "https://example.com/course",
+      name: "My Course",
+      lastSyncedAt: "2024-01-15T10:30:00.000Z",
+      modules: [
+        {
+          name: "Module 1",
+          slug: "abc12345",
+          lessons: [
+            {
+              name: "Lesson 1",
+              slug: "def67890",
+              url: "https://example.com/lesson/1",
+              isCompleted: true,
+              videoDownloaded: true,
+              contentSaved: true,
+            },
+          ],
+        },
+      ],
+    };
+    const result = courseSyncStateSchema.parse(input);
+    expect(result).toEqual(input);
+  });
+
+  it("applies default values for lesson flags", () => {
+    const input = {
+      url: "https://example.com/course",
+      name: "My Course",
+      modules: [
+        {
+          name: "Module 1",
+          slug: "abc12345",
+          lessons: [
+            {
+              name: "Lesson 1",
+              slug: "def67890",
+              url: "https://example.com/lesson/1",
+            },
+          ],
+        },
+      ],
+    };
+    const result = courseSyncStateSchema.parse(input);
+    const lesson = result.modules[0]?.lessons[0];
+    expect(lesson?.isCompleted).toBe(false);
+    expect(lesson?.videoDownloaded).toBe(false);
+    expect(lesson?.contentSaved).toBe(false);
+  });
+
+  it("rejects invalid URL", () => {
+    expect(() =>
+      courseSyncStateSchema.parse({
+        url: "not-a-url",
+        name: "Course",
+        modules: [],
+      })
+    ).toThrow();
+  });
+
+  it("rejects invalid datetime format", () => {
+    expect(() =>
+      courseSyncStateSchema.parse({
+        url: "https://example.com/course",
+        name: "Course",
+        lastSyncedAt: "invalid-date",
+        modules: [],
+      })
+    ).toThrow();
+  });
+});
+
+describe("sessionInfoSchema", () => {
+  it("validates complete session info", () => {
+    const input = {
+      domain: "example.com",
+      createdAt: "2024-01-15T10:30:00.000Z",
+      expiresAt: "2024-02-15T10:30:00.000Z",
+    };
+    const result = sessionInfoSchema.parse(input);
+    expect(result).toEqual(input);
+  });
+
+  it("accepts session without expiry", () => {
+    const input = {
+      domain: "example.com",
+      createdAt: "2024-01-15T10:30:00.000Z",
+    };
+    const result = sessionInfoSchema.parse(input);
+    expect(result.expiresAt).toBeUndefined();
+  });
+
+  it("rejects invalid createdAt datetime", () => {
+    expect(() =>
+      sessionInfoSchema.parse({
+        domain: "example.com",
+        createdAt: "not-a-date",
+      })
+    ).toThrow();
+  });
+
+  it("requires domain field", () => {
+    expect(() =>
+      sessionInfoSchema.parse({
+        createdAt: "2024-01-15T10:30:00.000Z",
+      })
+    ).toThrow();
+  });
+});

package/src/config/schema.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+/**
+ * Video quality preferences for downloads.
+ */
+export const VIDEO_QUALITY = {
+  highest: "highest",
+  lowest: "lowest",
+  "1080p": "1080p",
+  "720p": "720p",
+  "480p": "480p",
+} as const;
+
+export type VideoQuality = keyof typeof VIDEO_QUALITY;
+
+/**
+ * Global application configuration schema.
+ */
+export const configSchema = z.object({
+  outputDir: z.string().default("~/Downloads/offcourse"),
+  videoQuality: z.enum(["highest", "lowest", "1080p", "720p", "480p"]).default("highest"),
+  concurrency: z.number().int().min(1).max(5).default(2),
+  retryAttempts: z.number().int().min(0).max(10).default(3),
+  headless: z.boolean().default(true),
+});
+
+export type Config = z.infer<typeof configSchema>;
+
+/**
+ * Course sync state to track progress and enable resume.
+ */
+export const courseSyncStateSchema = z.object({
+  url: z.url(),
+  name: z.string(),
+  lastSyncedAt: z.iso.datetime().optional(),
+  modules: z.array(
+    z.object({
+      name: z.string(),
+      slug: z.string(),
+      lessons: z.array(
+        z.object({
+          name: z.string(),
+          slug: z.string(),
+          url: z.url(),
+          isCompleted: z.boolean().default(false),
+          videoDownloaded: z.boolean().default(false),
+          contentSaved: z.boolean().default(false),
+        })
+      ),
+    })
+  ),
+});
+
+export type CourseSyncState = z.infer<typeof courseSyncStateSchema>;
+
+/**
+ * Session info for a specific domain.
+ */
+export const sessionInfoSchema = z.object({
+  domain: z.string(),
+  createdAt: z.iso.datetime(),
+  expiresAt: z.iso.datetime().optional(),
+});
+
+export type SessionInfo = z.infer<typeof sessionInfoSchema>;