@przeprogramowani/10x-cli 1.8.0 → 1.9.0

package/README.md

@@ -47,6 +47,7 @@ Once installed, just tell your agent to **set up 10x-cli** and it will pick up t
 10x auth        # Authenticate with your email
 10x list        # Browse available modules and lessons
 10x get m1l1    # Fetch and apply lesson artifacts
+10x sync        # Update everything you've downloaded; show what changed
 10x doctor      # Check everything is working
 ```
 
@@ -57,6 +58,7 @@ Once installed, just tell your agent to **set up 10x-cli** and it will pick up t
 | `10x auth` | Magic-link login with your Circle-registered email |
 | `10x list` | Browse modules and lessons in your course |
 | `10x get <ref>` | Fetch a lesson and apply artifacts to your workspace |
+| `10x sync` | Bulk-download / refresh lessons and report what changed upstream |
 | `10x doctor` | Diagnose auth, API connectivity, and local config |
 
 ### `10x get` Flags
@@ -104,6 +106,63 @@ Once installed, just tell your agent to **set up 10x-cli** and it will pick up t
 > `--type rules` request overrides the opt-out for that run. Skills, prompts,
 > and config-templates are unaffected.
 
+### `10x sync`
+
+`10x sync` keeps your downloaded lessons up to date and tells you **what changed
+upstream** since you last fetched. By default it refreshes only the lessons you've
+already downloaded; `--all` pulls every unlocked lesson at once.
+
+Unchanged lessons are skipped **without a download** — the catalog advertises a
+per-lesson `contentHash` that the CLI compares against what it last applied, so the
+common "nothing changed" case is a single catalog request.
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Sync every unlocked lesson, not just the ones you've downloaded |
+| `--module <m>` | Limit to one module (e.g. `m2` or `2`) |
+| `--dry-run` | Preview what would change without writing anything |
+| `--force` | Ignore the cheap-skip digest and overwrite local edits with upstream |
+| `--tool <tool>` | AI coding tool (same set as `get`) |
+| `--lang <lang>` | Content language: `en` (default) or `pl` |
+| `--course <slug>` | Override the course slug (default: `10xdevs3`) |
+| `--no-course-rules` | Skip the course rules block (same semantics as `get`) |
+
+```bash
+# Refresh everything you've already downloaded; report what moved
+10x sync
+
+# Pull every unlocked lesson in one shot (fresh project)
+10x sync --all
+
+# Preview changes without writing
+10x sync --dry-run
+
+# Only module 2
+10x sync --module m2
+
+# Take all upstream updates, overwriting local edits
+10x sync --force
+```
+
+The report classifies every resource as **upstream-updated**, **created**,
+**unchanged**, **skipped (conflict)**, or **removed**. When a file you edited
+locally also changed upstream, sync **keeps your edit** and prints the exact
+command to take the update, e.g.:
+
+```
+m2l3 — conflicts (1 skipped)
+    skipped skills/auth-skill (SKILL.md) — you edited it → 10x get m2l3 --type skills --name auth-skill
+```
+
+Run that `10x get …` to take a single update, or `10x sync --force` to take them
+all. **Change visibility covers skills and prompts** — configs are create-only
+(never overwritten) and rules are sentinel-managed, so they aren't part of the
+"what changed" report.
+
+**Exit code is worst-outcome:** `0` when everything is clean/unchanged (a skipped
+conflict is reported, not a failure), `1` if any lesson failed to fetch. The full
+report is still emitted on a partial failure.
+
 ### Global Flags
 
 - `--json` — Machine-readable JSON output (auto-detected when piped)

package/dist/index.mjs

@@ -2271,7 +2271,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "@przeprogramowani/10x-cli",
-  version: "1.8.0",
+  version: "1.9.0",
   description: "Open-source CLI for 10xDevs course content",
   repository: {
     type: "git",
@@ -4224,7 +4224,7 @@ function parseModuleRef(raw) {
 
 // src/lib/manifest.ts
 import { createHash as createHash2 } from "node:crypto";
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync2, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname2, join as join3 } from "node:path";
 var MANIFEST_FILENAME = ".10x-cli-manifest.json";
 var CLI_PACKAGE_NAME = "@przeprogramowani/10x-cli";
@@ -4258,8 +4258,11 @@ function writeManifest(dir, manifest) {
   }
   const manifestPath = join3(dir, MANIFEST_FILENAME);
   mkdirSync3(dirname2(manifestPath), { recursive: true });
-  writeFileSync2(manifestPath, `${JSON.stringify(manifest, null, 2)}
+  const tmp = `${manifestPath}.tmp`;
+  rmSync2(tmp, { force: true });
+  writeFileSync2(tmp, `${JSON.stringify(manifest, null, 2)}
 `);
+  renameSync2(tmp, manifestPath);
 }
 function isManifest(value) {
   if (typeof value !== "object" || value === null)
@@ -4318,6 +4321,9 @@ function isLessonFilesEntry(value) {
     if (!isStringArray(skill["files"]))
       return false;
   }
+  if (e2["catalogContentHash"] !== undefined && typeof e2["catalogContentHash"] !== "string") {
+    return false;
+  }
   return isStringArray(e2["prompts"]) && isStringArray(e2["configs"]);
 }
 function isLessonsRecord(value) {
@@ -4469,9 +4475,9 @@ import {
   lstatSync,
   mkdirSync as mkdirSync5,
   readFileSync as readFileSync5,
-  renameSync as renameSync2,
+  renameSync as renameSync3,
   rmdirSync as rmdirSync2,
-  rmSync as rmSync3,
+  rmSync as rmSync4,
   statSync,
   writeFileSync as writeFileSync4
 } from "node:fs";
@@ -4562,7 +4568,7 @@ import {
   readFileSync as readFileSync4,
   readdirSync,
   rmdirSync,
-  rmSync as rmSync2,
+  rmSync as rmSync3,
   writeFileSync as writeFileSync3
 } from "node:fs";
 import { dirname as dirname3, join as join5 } from "node:path";
@@ -4577,28 +4583,22 @@ async function applyBundle(bundle, projectRoot, options = {}) {
   const applyCourseRules = options.applyCourseRules !== false;
   const manifestDir = join5(projectRoot, profile.manifestDir);
   const prevManifest = readManifest(manifestDir);
-  for (const skill of bundle.skills) {
-    assertSafeName(skill.name, "skill");
-    for (const file of skill.files) {
-      assertSafeSkillFilePath(file.path, skill.name);
-    }
-  }
-  for (const prompt of bundle.prompts)
-    assertSafeName(prompt.name, "prompt");
-  for (const config of bundle.configs)
-    assertSafeName(config.name, "config");
+  const plan = planBundle(bundle, projectRoot, { profile, applyCourseRules });
   const nextSkillHashes = {};
   const nextPromptHashes = {};
   const skills = [];
-  for (const skill of bundle.skills) {
-    const skillDir = join5(projectRoot, profile.skillDir(skill.name));
+  for (let si = 0;si < bundle.skills.length; si++) {
+    const skill = bundle.skills[si];
+    const planSkill = plan.skills[si];
     const prevEntry = prevManifest?.files.skills[skill.name];
     const fileWrites = [];
     const skillHashes = {};
-    for (const file of skill.files) {
-      const target = join5(skillDir, file.path);
+    for (let fi = 0;fi < skill.files.length; fi++) {
+      const file = skill.files[fi];
+      const planFile = planSkill.files[fi];
+      const target = planFile.path;
       const storedHash = prevEntry?.contentHashes?.[file.path];
-      const { action, isConflict } = computeFileAction(target, file.content, storedHash);
+      const { action, isConflict } = planFile;
       let finalAction = action;
       let userBackupPath;
       if (isConflict) {
@@ -4641,11 +4641,13 @@ async function applyBundle(bundle, projectRoot, options = {}) {
     skills.push({ name: skill.name, files: fileWrites });
   }
   const prompts = [];
-  for (const prompt of bundle.prompts) {
-    const target = join5(projectRoot, profile.promptPath(prompt.name));
+  for (let pi = 0;pi < bundle.prompts.length; pi++) {
+    const prompt = bundle.prompts[pi];
+    const planPrompt = plan.prompts[pi];
+    const target = planPrompt.path;
     const promptFilename = `${prompt.name}.md`;
     const storedHash = prevManifest?.files.promptHashes?.[promptFilename];
-    const { action, isConflict } = computeFileAction(target, prompt.content, storedHash);
+    const { action, isConflict } = planPrompt;
     let finalAction = action;
     let userBackupPath;
     if (isConflict) {
@@ -4683,42 +4685,16 @@ async function applyBundle(bundle, projectRoot, options = {}) {
   }
   const rulesFilePath = join5(projectRoot, profile.rulesFile);
   const existingRules = readFileOrEmpty(rulesFilePath);
-  let rulesAction;
-  if (!applyCourseRules) {
-    const { content: stripped, removed: removed2 } = removeRulesBlockWithMarkers(existingRules, profile.sentinelBegin, profile.sentinelEnd);
-    if (removed2 && stripped !== existingRules) {
-      rulesAction = "removed";
-      if (!dryRun) {
-        writeFileAt(rulesFilePath, stripped);
-      }
-    } else {
-      rulesAction = "unchanged";
-    }
-  } else if (bundle.rules.length === 0) {
-    rulesAction = "unchanged";
-  } else {
-    const rulesBody = bundle.rules.map((r2) => r2.content.trim()).join(`
-
-`);
-    const { content: newRules } = applyRulesBlockWithMarkers(existingRules, rulesBody, profile.sentinelBegin, profile.sentinelEnd);
-    if (newRules === existingRules) {
-      rulesAction = "unchanged";
-    } else if (existingRules.length === 0) {
-      rulesAction = "created";
-    } else {
-      rulesAction = "updated";
-    }
-    if (!dryRun && rulesAction !== "unchanged") {
-      writeFileAt(rulesFilePath, newRules);
-    }
+  const { action: rulesAction, content: newRulesContent } = planRules(existingRules, bundle, profile, applyCourseRules);
+  if (!dryRun && rulesAction !== "unchanged") {
+    writeFileAt(rulesFilePath, newRulesContent);
   }
-  const configs = bundle.configs.map((config) => {
-    const target = join5(projectRoot, profile.configPath(config.name));
-    const action = existsSync5(target) ? "skipped" : "created";
-    if (!dryRun && action === "created") {
-      writeFileAt(target, config.content);
+  const configs = bundle.configs.map((config, ci) => {
+    const planConfig = plan.configs[ci];
+    if (!dryRun && planConfig.action === "created") {
+      writeFileAt(planConfig.path, config.content);
     }
-    return { name: config.name, path: target, action };
+    return { name: config.name, path: planConfig.path, action: planConfig.action };
   });
   const removed = computeRemovals(prevManifest, bundle, profile, projectRoot);
   const removalResult = {
@@ -4729,31 +4705,33 @@ async function applyBundle(bundle, projectRoot, options = {}) {
   for (const entry of removed.skillDirs) {
     removalResult.skills.push({ name: entry.name, path: entry.path, action: "removed" });
     if (!dryRun && !partial)
-      rmSync2(entry.path, { recursive: true, force: true });
+      rmSync3(entry.path, { recursive: true, force: true });
   }
   for (const entry of removed.skillFiles) {
     removalResult.skills.push({ name: entry.name, path: entry.path, action: "removed" });
     if (!dryRun && !partial) {
-      rmSync2(entry.path, { force: true });
+      rmSync3(entry.path, { force: true });
       removeEmptyParentDirs(entry.path, entry.skillDirAbs);
     }
   }
   for (const entry of removed.prompts) {
     removalResult.prompts.push({ name: entry.name, path: entry.path, action: "removed" });
     if (!dryRun && !partial)
-      rmSync2(entry.path, { force: true });
+      rmSync3(entry.path, { force: true });
   }
   for (const entry of removed.configs) {
     removalResult.configs.push({ name: entry.name, path: entry.path, action: "removed" });
     if (!dryRun && !partial)
-      rmSync2(entry.path, { force: true });
+      rmSync3(entry.path, { force: true });
   }
   if (!dryRun && !partial) {
+    const catalogContentHash = options.catalogContentHash ?? prevManifest?.lessons?.[bundle.lessonId]?.catalogContentHash;
     const newLessonEntry = {
       appliedAt: new Date().toISOString(),
       skills: Object.fromEntries(bundle.skills.map((s) => [s.name, { files: s.files.map((f2) => f2.path) }])),
       prompts: bundle.prompts.map((p2) => `${p2.name}.md`),
-      configs: bundle.configs.map((c2) => c2.name)
+      configs: bundle.configs.map((c2) => c2.name),
+      ...catalogContentHash !== undefined ? { catalogContentHash } : {}
     };
     let baseLessons = {};
     if (prevManifest && !prevManifest.lessons) {
@@ -4813,6 +4791,107 @@ async function applyBundle(bundle, projectRoot, options = {}) {
     removals: removalResult
   };
 }
+function planBundle(bundle, projectRoot, options = {}) {
+  const profile = options.profile ?? PROFILES[DEFAULT_TOOL];
+  const applyCourseRules = options.applyCourseRules !== false;
+  for (const skill of bundle.skills) {
+    assertSafeName(skill.name, "skill");
+    for (const file of skill.files)
+      assertSafeSkillFilePath(file.path, skill.name);
+  }
+  for (const prompt of bundle.prompts)
+    assertSafeName(prompt.name, "prompt");
+  for (const config of bundle.configs)
+    assertSafeName(config.name, "config");
+  const manifestDir = join5(projectRoot, profile.manifestDir);
+  const prevManifest = readManifest(manifestDir);
+  const skills = bundle.skills.map((skill) => {
+    const skillDir = join5(projectRoot, profile.skillDir(skill.name));
+    const prevEntry = prevManifest?.files.skills[skill.name];
+    const files = skill.files.map((file) => {
+      const target = join5(skillDir, file.path);
+      const storedHash = prevEntry?.contentHashes?.[file.path];
+      const { action, isConflict } = computeFileAction(target, file.content, storedHash);
+      return {
+        relativePath: file.path,
+        path: target,
+        action,
+        isConflict,
+        upstreamChanged: computeUpstreamChanged(file.content, storedHash, action)
+      };
+    });
+    return { name: skill.name, files };
+  });
+  const prompts = bundle.prompts.map((prompt) => {
+    const target = join5(projectRoot, profile.promptPath(prompt.name));
+    const storedHash = prevManifest?.files.promptHashes?.[`${prompt.name}.md`];
+    const { action, isConflict } = computeFileAction(target, prompt.content, storedHash);
+    return {
+      name: prompt.name,
+      path: target,
+      action,
+      isConflict,
+      upstreamChanged: computeUpstreamChanged(prompt.content, storedHash, action)
+    };
+  });
+  const rulesFilePath = join5(projectRoot, profile.rulesFile);
+  const existingRules = readFileOrEmpty(rulesFilePath);
+  const { action: rulesAction } = planRules(existingRules, bundle, profile, applyCourseRules);
+  const configs = bundle.configs.map((config) => {
+    const target = join5(projectRoot, profile.configPath(config.name));
+    const action = existsSync5(target) ? "skipped" : "created";
+    return {
+      name: config.name,
+      path: target,
+      action,
+      isConflict: false,
+      upstreamChanged: action === "created"
+    };
+  });
+  const removed = computeRemovals(prevManifest, bundle, profile, projectRoot);
+  const removals = {
+    skills: [
+      ...removed.skillDirs.map((e2) => ({ name: e2.name, path: e2.path })),
+      ...removed.skillFiles.map((e2) => ({ name: e2.name, path: e2.path }))
+    ],
+    prompts: removed.prompts.map((e2) => ({ name: e2.name, path: e2.path })),
+    configs: removed.configs.map((e2) => ({ name: e2.name, path: e2.path }))
+  };
+  return {
+    skills,
+    prompts,
+    rules: { action: rulesAction, upstreamChanged: rulesAction !== "unchanged" },
+    configs,
+    removals
+  };
+}
+function computeUpstreamChanged(newContent, storedHash, action) {
+  if (storedHash === undefined)
+    return action !== "unchanged";
+  return contentHash(newContent) !== storedHash;
+}
+function planRules(existingRules, bundle, profile, applyCourseRules) {
+  if (!applyCourseRules) {
+    const { content: stripped, removed } = removeRulesBlockWithMarkers(existingRules, profile.sentinelBegin, profile.sentinelEnd);
+    if (removed && stripped !== existingRules)
+      return { action: "removed", content: stripped };
+    return { action: "unchanged", content: existingRules };
+  }
+  if (bundle.rules.length === 0)
+    return { action: "unchanged", content: existingRules };
+  const rulesBody = bundle.rules.map((r2) => r2.content.trim()).join(`
+
+`);
+  const { content: newRules } = applyRulesBlockWithMarkers(existingRules, rulesBody, profile.sentinelBegin, profile.sentinelEnd);
+  let action;
+  if (newRules === existingRules)
+    action = "unchanged";
+  else if (existingRules.length === 0)
+    action = "created";
+  else
+    action = "updated";
+  return { action, content: newRules };
+}
 function computeFileAction(filePath, newContent, storedHash) {
   if (!existsSync5(filePath))
     return { action: "created", isConflict: false };
@@ -5102,7 +5181,7 @@ function migrateArtifacts(projectRoot, orphan, newProfile) {
     }
   }
   summary.sentinelStripped = stripSentinelFromRulesFile(projectRoot, oldProfile);
-  rmSync3(orphan.manifestPath, { force: true });
+  rmSync4(orphan.manifestPath, { force: true });
   tryRemoveEmptyDir(join6(projectRoot, oldProfile.manifestDir));
   return summary;
 }
@@ -5129,9 +5208,9 @@ function deleteArtifacts(projectRoot, orphan) {
         });
         continue;
       }
-      rmSync3(join6(skillDir, relPath), { force: true });
+      rmSync4(join6(skillDir, relPath), { force: true });
     }
-    rmSync3(skillDir, { recursive: true, force: true });
+    rmSync4(skillDir, { recursive: true, force: true });
     summary.movedOrRemoved.skills.push(skillName);
   }
   for (const promptFile of orphan.manifest.files.prompts) {
@@ -5140,7 +5219,7 @@ function deleteArtifacts(projectRoot, orphan) {
       continue;
     }
     const promptName = promptFile.replace(/\.md$/, "");
-    rmSync3(join6(projectRoot, oldProfile.promptPath(promptName)), { force: true });
+    rmSync4(join6(projectRoot, oldProfile.promptPath(promptName)), { force: true });
     summary.movedOrRemoved.prompts.push(promptFile);
   }
   for (const configFile of orphan.manifest.files.configs) {
@@ -5148,11 +5227,11 @@ function deleteArtifacts(projectRoot, orphan) {
       summary.skipped.push({ path: configFile, reason: "unsafe name in manifest" });
       continue;
     }
-    rmSync3(join6(projectRoot, oldProfile.configPath(configFile)), { force: true });
+    rmSync4(join6(projectRoot, oldProfile.configPath(configFile)), { force: true });
     summary.movedOrRemoved.configs.push(configFile);
   }
   summary.sentinelStripped = stripSentinelFromRulesFile(projectRoot, oldProfile);
-  rmSync3(orphan.manifestPath, { force: true });
+  rmSync4(orphan.manifestPath, { force: true });
   const manifestDirAbs = join6(projectRoot, oldProfile.manifestDir);
   tryRemoveEmptyDir(join6(manifestDirAbs, "skills"));
   tryRemoveEmptyDir(join6(manifestDirAbs, "prompts"));
@@ -5176,12 +5255,12 @@ function moveIfSafe(from, to, skipped) {
       });
       return false;
     }
-    rmSync3(from, { force: true });
+    rmSync4(from, { force: true });
     return true;
   }
   mkdirSync5(dirname4(to), { recursive: true });
   try {
-    renameSync2(from, to);
+    renameSync3(from, to);
   } catch (err) {
     const code = err?.code;
     if (code !== "EXDEV")
@@ -5189,9 +5268,9 @@ function moveIfSafe(from, to, skipped) {
     const bytes = readFileSync5(from);
     const tmp = `${to}.tmp`;
     writeFileSync4(tmp, bytes);
-    renameSync2(tmp, to);
+    renameSync3(tmp, to);
     try {
-      rmSync3(from, { force: true });
+      rmSync4(from, { force: true });
     } catch {
       skipped.push({
         path: from,
@@ -5213,7 +5292,7 @@ function stripSentinelFromRulesFile(projectRoot, oldProfile) {
   if (!removed)
     return false;
   if (content.trim().length === 0) {
-    rmSync3(rulesPath, { force: true });
+    rmSync4(rulesPath, { force: true });
   } else {
     writeFileSync4(rulesPath, content);
   }
@@ -5807,6 +5886,408 @@ function renderModuleDetail(ctx, module) {
 `), undefined);
 }
 
+// src/commands/sync.ts
+import { join as join8 } from "node:path";
+var DEFAULT_COURSE4 = "10xdevs3";
+var SUPPORTED_LANGS = ["en", "pl"];
+function registerSyncCommand(cli) {
+  cli.command("sync", "Bulk-download and update lessons, reporting what changed upstream").option("--all", "Sync every unlocked lesson (default: only lessons you've already downloaded)").option("--dry-run", "Show what would change without writing").option("--force", "Ignore the cheap-skip digest and overwrite local edits with upstream").option("--module <module>", "Limit to one module (e.g. 'm2' or '2')").option("--course <course>", "Override the course slug (default: 10xdevs3)").option("--tool <tool>", "AI coding tool (claude-code, cursor, copilot, codex, windsurf, gemini, generic)").option("--lang <lang>", "Content language: en (default) or pl").option("--no-course-rules", "Skip applying the course rules block to your rules file (CLAUDE.md/AGENTS.md)").action(async (options) => {
+    const ctx = resolveContext(options);
+    await runSync(ctx, options);
+  });
+}
+async function runSync(ctx, options) {
+  if (options.lang && !SUPPORTED_LANGS.includes(options.lang)) {
+    outputError(ctx, "invalid_lang", `Unknown language '${options.lang}'.`, ExitCodes.USAGE, `Supported languages: ${SUPPORTED_LANGS.join(", ")}`);
+  }
+  let moduleFilter;
+  if (options.module !== undefined) {
+    const parsed = parseModule(options.module);
+    if (parsed === null) {
+      outputError(ctx, "invalid_module", `'${options.module}' is not a valid module.`, ExitCodes.USAGE, "Use a module number like '2' or 'm2'.");
+    }
+    moduleFilter = parsed;
+  }
+  const auth = await requireAuth(ctx);
+  const course = options.course ?? DEFAULT_COURSE4;
+  const profile = await resolveToolProfile(options.tool, process.cwd());
+  const dryRun = options.dryRun === true;
+  const force = options.force === true;
+  const lang = options.lang ?? readToolConfig()?.lang ?? "en";
+  const explicitCourseRules = resolveCourseRulesFlag(process.argv);
+  const applyCourseRules = explicitCourseRules ?? readToolConfig()?.courseRules ?? true;
+  verbose(ctx, `fetching catalog ${course}`);
+  const catalogResult = await fetchCatalog(course, auth.access_token);
+  if (!catalogResult.ok) {
+    handleCatalogError(ctx, catalogResult.status, catalogResult.code, catalogResult.error);
+  }
+  const catalog = catalogResult.data;
+  const moduleState = new Map;
+  for (const mod of catalog.modules)
+    moduleState.set(mod.module, mod.effectiveState);
+  const exclusions = [];
+  const unlocked = catalog.lessons.filter((lesson) => {
+    if (moduleState.get(lesson.module) === "locked") {
+      exclusions.push({ lessonId: lesson.lessonId, reason: `module ${lesson.module} is locked` });
+      return false;
+    }
+    return true;
+  });
+  const manifest = readManifest(join8(process.cwd(), profile.manifestDir));
+  const manifestLessonIds = new Set(manifest?.lessons ? Object.keys(manifest.lessons) : []);
+  let targets = unlocked;
+  if (moduleFilter !== undefined)
+    targets = targets.filter((l2) => l2.module === moduleFilter);
+  if (options.all !== true)
+    targets = targets.filter((l2) => manifestLessonIds.has(l2.lessonId));
+  targets = [...targets].sort((a2, b2) => a2.module - b2.module || a2.lesson - b2.lesson);
+  const controller = new AbortController;
+  const onSigint = () => controller.abort();
+  process.once("SIGINT", onSigint);
+  const outcomes = [];
+  try {
+    for (const lesson of targets) {
+      if (controller.signal.aborted)
+        break;
+      outcomes.push(await syncLesson(ctx, lesson, {
+        course,
+        profile,
+        lang,
+        dryRun,
+        force,
+        applyCourseRules,
+        token: auth.access_token,
+        manifest,
+        signal: controller.signal
+      }));
+    }
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+  renderReport(ctx, profile, {
+    course,
+    dryRun,
+    force,
+    mode: options.all === true ? "all" : "downloaded",
+    module: moduleFilter,
+    outcomes,
+    exclusions
+  });
+  if (outcomes.some((o) => o.status === "errored")) {
+    process.exit(ExitCodes.ERROR);
+  }
+}
+async function syncLesson(ctx, lesson, opts) {
+  const stored = opts.manifest?.lessons?.[lesson.lessonId]?.catalogContentHash;
+  if (!opts.force && lesson.contentHash !== undefined && stored !== undefined && lesson.contentHash === stored) {
+    verbose(ctx, `${lesson.lessonId}: upstream unchanged (digest match) — skipping fetch`);
+    return {
+      lessonId: lesson.lessonId,
+      title: lesson.title,
+      fetched: false,
+      status: "unchanged",
+      resources: []
+    };
+  }
+  verbose(ctx, `${lesson.lessonId}: fetching`);
+  const result = await fetchLesson(opts.course, lesson.lessonId, opts.token, {
+    lang: opts.lang,
+    tool: opts.profile.toolId,
+    signal: opts.signal
+  });
+  if (!result.ok) {
+    return {
+      lessonId: lesson.lessonId,
+      title: lesson.title,
+      fetched: true,
+      status: "errored",
+      resources: [],
+      error: {
+        code: result.code || "lesson_fetch_failed",
+        message: lessonErrorMessage(result.status, result.code, result.error),
+        retry: `10x get ${lesson.lessonId}`
+      }
+    };
+  }
+  const bundle = result.data;
+  if (opts.dryRun) {
+    const plan = planBundle(bundle, process.cwd(), {
+      profile: opts.profile,
+      applyCourseRules: opts.applyCourseRules
+    });
+    const resources2 = classifyFromPlan(plan, lesson.lessonId, opts.force);
+    return {
+      lessonId: lesson.lessonId,
+      title: lesson.title,
+      fetched: true,
+      status: lessonStatus(resources2),
+      resources: resources2
+    };
+  }
+  const onConflict = opts.force ? async () => "overwrite" : async () => "skip";
+  const writeResult = await applyBundle(bundle, process.cwd(), {
+    course: opts.course,
+    profile: opts.profile,
+    onConflict,
+    applyCourseRules: opts.applyCourseRules,
+    catalogContentHash: lesson.contentHash
+  });
+  const resources = classifyFromWriteResult(writeResult, lesson.lessonId);
+  return {
+    lessonId: lesson.lessonId,
+    title: lesson.title,
+    fetched: true,
+    status: lessonStatus(resources),
+    resources
+  };
+}
+function actionToBucket(action) {
+  switch (action) {
+    case "created":
+      return "created";
+    case "updated":
+    case "conflict_overwritten":
+    case "conflict_saved_user":
+      return "upstream-updated";
+    case "conflict_skipped":
+      return "skipped-conflict";
+    case "removed":
+      return "removed";
+    case "unchanged":
+    case "skipped":
+    default:
+      return "unchanged";
+  }
+}
+function remediation(lessonId, type, name) {
+  return `10x get ${lessonId} --type ${type} --name ${name}`;
+}
+function classifyFromWriteResult(result, lessonId) {
+  const out = [];
+  for (const skill of result.skills) {
+    for (const file of skill.files) {
+      const bucket = actionToBucket(file.action);
+      out.push({
+        type: "skills",
+        name: skill.name,
+        file: file.path,
+        bucket,
+        ...bucket === "skipped-conflict" ? { remediation: remediation(lessonId, "skills", skill.name) } : {}
+      });
+    }
+  }
+  for (const prompt of result.prompts) {
+    const bucket = actionToBucket(prompt.action);
+    out.push({
+      type: "prompts",
+      name: prompt.name,
+      bucket,
+      ...bucket === "skipped-conflict" ? { remediation: remediation(lessonId, "prompts", prompt.name) } : {}
+    });
+  }
+  out.push({ type: "rules", name: "course-rules", bucket: actionToBucket(result.rules.action) });
+  for (const config of result.configs) {
+    out.push({ type: "configs", name: config.name, bucket: actionToBucket(config.action) });
+  }
+  for (const entry of result.removals.skills) {
+    out.push({ type: "skills", name: entry.name, bucket: "removed" });
+  }
+  for (const entry of result.removals.prompts) {
+    out.push({ type: "prompts", name: entry.name, bucket: "removed" });
+  }
+  for (const entry of result.removals.configs) {
+    out.push({ type: "configs", name: entry.name, bucket: "removed" });
+  }
+  return out;
+}
+function classifyFromPlan(plan, lessonId, force) {
+  const out = [];
+  const conflictBucket = force ? "upstream-updated" : "skipped-conflict";
+  for (const skill of plan.skills) {
+    for (const file of skill.files) {
+      const bucket = file.isConflict ? conflictBucket : actionToBucket(file.action);
+      out.push({
+        type: "skills",
+        name: skill.name,
+        file: file.relativePath,
+        bucket,
+        ...bucket === "skipped-conflict" ? { remediation: remediation(lessonId, "skills", skill.name) } : {}
+      });
+    }
+  }
+  for (const prompt of plan.prompts) {
+    const bucket = prompt.isConflict ? conflictBucket : actionToBucket(prompt.action);
+    out.push({
+      type: "prompts",
+      name: prompt.name,
+      bucket,
+      ...bucket === "skipped-conflict" ? { remediation: remediation(lessonId, "prompts", prompt.name) } : {}
+    });
+  }
+  out.push({ type: "rules", name: "course-rules", bucket: actionToBucket(plan.rules.action) });
+  for (const config of plan.configs) {
+    out.push({ type: "configs", name: config.name, bucket: actionToBucket(config.action) });
+  }
+  for (const entry of plan.removals.skills) {
+    out.push({ type: "skills", name: entry.name, bucket: "removed" });
+  }
+  for (const entry of plan.removals.prompts) {
+    out.push({ type: "prompts", name: entry.name, bucket: "removed" });
+  }
+  for (const entry of plan.removals.configs) {
+    out.push({ type: "configs", name: entry.name, bucket: "removed" });
+  }
+  return out;
+}
+function lessonStatus(resources) {
+  if (resources.some((r2) => r2.bucket === "created" || r2.bucket === "upstream-updated" || r2.bucket === "removed")) {
+    return "updated";
+  }
+  if (resources.some((r2) => r2.bucket === "skipped-conflict"))
+    return "conflicts";
+  return "unchanged";
+}
+function countBuckets(outcomes) {
+  const totals = {
+    created: 0,
+    "upstream-updated": 0,
+    unchanged: 0,
+    "skipped-conflict": 0,
+    removed: 0
+  };
+  for (const o of outcomes) {
+    for (const r2 of o.resources)
+      totals[r2.bucket]++;
+  }
+  return totals;
+}
+function renderReport(ctx, profile, input) {
+  const { outcomes, exclusions } = input;
+  const buckets = countBuckets(outcomes);
+  const lessonsErrored = outcomes.filter((o) => o.status === "errored").length;
+  const lessonsConflicts = outcomes.filter((o) => o.status === "conflicts").length;
+  if (ctx.json) {
+    output(ctx, "", {
+      course: input.course,
+      tool: profile.toolId,
+      dryRun: input.dryRun,
+      force: input.force,
+      mode: input.mode,
+      module: input.module ?? null,
+      lessons: outcomes,
+      excluded: exclusions,
+      totals: {
+        lessons: outcomes.length,
+        updated: outcomes.filter((o) => o.status === "updated").length,
+        unchanged: outcomes.filter((o) => o.status === "unchanged").length,
+        conflicts: lessonsConflicts,
+        errored: lessonsErrored,
+        excluded: exclusions.length,
+        resources: {
+          created: buckets.created,
+          upstreamUpdated: buckets["upstream-updated"],
+          unchanged: buckets.unchanged,
+          skippedConflict: buckets["skipped-conflict"],
+          removed: buckets.removed
+        }
+      }
+    });
+    return;
+  }
+  const lines = [];
+  const verb = input.dryRun ? "Would sync" : "Synced";
+  const scope = input.mode === "all" ? "all unlocked lessons" : "downloaded lessons";
+  const moduleNote = input.module !== undefined ? ` in module ${input.module}` : "";
+  lines.push(`${verb} ${input.course} — ${scope}${moduleNote}:`);
+  if (outcomes.length === 0) {
+    lines.push("  (nothing to sync)");
+  }
+  for (const o of outcomes) {
+    if (o.status === "errored") {
+      lines.push(`  ${o.lessonId} — error: ${o.error?.message ?? "failed"}`);
+      if (o.error)
+        lines.push(`      → retry: ${o.error.retry}`);
+      continue;
+    }
+    const summary = summarizeLesson(o);
+    lines.push(`  ${o.lessonId} — ${o.status}${summary ? ` (${summary})` : ""}`);
+    for (const r2 of o.resources) {
+      if (r2.bucket !== "skipped-conflict")
+        continue;
+      const label = r2.file ? `${r2.type}/${r2.name} (${r2.file})` : `${r2.type}/${r2.name}`;
+      lines.push(`      skipped ${label} — you edited it → ${r2.remediation}`);
+    }
+  }
+  if (exclusions.length > 0) {
+    lines.push("");
+    lines.push("Excluded:");
+    for (const ex of exclusions)
+      lines.push(`  ${ex.lessonId} — ${ex.reason}`);
+  }
+  lines.push("");
+  lines.push(`Totals: ${buckets["upstream-updated"]} updated, ${buckets.created} new, ` + `${buckets.unchanged} unchanged, ${buckets["skipped-conflict"]} skipped (conflicts), ` + `${buckets.removed} removed.`);
+  if (lessonsConflicts > 0 && !input.force) {
+    lines.push("To take all upstream updates over your local edits: 10x sync --force");
+  }
+  output(ctx, lines.join(`
+`), undefined);
+}
+function summarizeLesson(o) {
+  const counts = {
+    created: 0,
+    "upstream-updated": 0,
+    unchanged: 0,
+    "skipped-conflict": 0,
+    removed: 0
+  };
+  for (const r2 of o.resources)
+    counts[r2.bucket]++;
+  const parts = [];
+  if (counts["upstream-updated"])
+    parts.push(`${counts["upstream-updated"]} updated`);
+  if (counts.created)
+    parts.push(`${counts.created} new`);
+  if (counts["skipped-conflict"])
+    parts.push(`${counts["skipped-conflict"]} skipped`);
+  if (counts.removed)
+    parts.push(`${counts.removed} removed`);
+  if (!o.fetched)
+    parts.push("not downloaded");
+  return parts.join(", ");
+}
+function handleCatalogError(ctx, status, code, error) {
+  if (status === 401) {
+    outputError(ctx, "auth_required", "Your session is no longer valid.", ExitCodes.AUTH_REQUIRED, "Run '10x auth' to log in again.");
+  }
+  if (status === 404) {
+    outputError(ctx, "course_not_found", "Couldn't find that course.", ExitCodes.NOT_FOUND, "Check the --course slug, or omit it to use the default.");
+  }
+  if (status === 0) {
+    outputError(ctx, "network_error", "Could not reach the 10x-toolkit API.", ExitCodes.ERROR, "Check your internet connection and run the command again.");
+  }
+  outputError(ctx, code || "catalog_fetch_failed", "Failed to fetch the course catalog.", ExitCodes.ERROR, error ? `Server said: ${error}` : undefined);
+}
+function lessonErrorMessage(status, code, error) {
+  if (status === 403)
+    return "Module is locked.";
+  if (status === 404)
+    return "Lesson not found.";
+  if (status === 401)
+    return "Session expired.";
+  if (status === 0)
+    return "Network error reaching the API.";
+  if (code === "signature_error" || code === "signature_missing" || code === "signature_internal_error") {
+    return "Bundle signature verification failed.";
+  }
+  return error ? `Fetch failed: ${error}` : "Fetch failed.";
+}
+function parseModule(value) {
+  const match = /^m?(\d+)$/i.exec(value.trim());
+  if (!match)
+    return null;
+  return Number(match[1]);
+}
+
 // src/index.ts
 var cli = cac("10x");
 cli.option("--json", "Output as JSON (auto-detected when piped)");
@@ -5814,6 +6295,7 @@ cli.option("--verbose", "Show detailed output on stderr");
 registerAuthCommand(cli);
 registerGetCommand(cli);
 registerListCommand(cli);
+registerSyncCommand(cli);
 registerDoctorCommand(cli);
 cli.help();
 cli.version(package_default.version);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@przeprogramowani/10x-cli",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Open-source CLI for 10xDevs course content",
   "repository": {
     "type": "git",