@przeprogramowani/10x-cli 1.1.0 → 1.2.0

package/README.md

@@ -3,10 +3,18 @@
 CLI tool for [10xDevs](https://10xdevs.pl) course content. Fetch and apply AI coding skills,
 prompts, and configs directly into your workspace.
 
+## Requirements
+
+- **Node 20+** — this is the only runtime dependency.
+
 ## Install
 
 ```bash
-# npm (recommended)
+# Zero-install — run directly with npx (no global install needed)
+npx @przeprogramowani/10x-cli auth
+npx @przeprogramowani/10x-cli get m1l1
+
+# Or install globally for shorter commands
 npm install -g @przeprogramowani/10x-cli
 
 # Or download a standalone binary from GitHub Releases

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.1.0",
+  version: "1.2.0",
   description: "Open-source CLI for 10xDevs course content",
   repository: {
     type: "git",
@@ -3565,6 +3565,8 @@ async function fetchLesson(course, lessonId, token, options = {}) {
   const params = new URLSearchParams;
   if (options.lang)
     params.set("lang", options.lang);
+  if (options.tool)
+    params.set("tool", options.tool);
   const qs = params.toString();
   const path = `/api/lessons/${encodeURIComponent(course)}/${encodeURIComponent(lessonId)}${qs ? `?${qs}` : ""}`;
   const result = await apiGet(path, { token, signal: options.signal });
@@ -3699,10 +3701,89 @@ function formatReleaseAt(iso, now = new Date) {
   return `${absolute} (in ${days} days)`;
 }
 
+// src/lib/tool-profile.ts
+var SENTINEL_BEGIN = "<!-- BEGIN @przeprogramowani/10x-cli -->";
+var SENTINEL_END = "<!-- END @przeprogramowani/10x-cli -->";
+var PROFILES = {
+  "claude-code": {
+    toolId: "claude-code",
+    displayName: "Claude Code",
+    skillPath: (n) => `.claude/skills/${n}/SKILL.md`,
+    skillDir: (n) => `.claude/skills/${n}`,
+    promptPath: (n) => `.claude/prompts/${n}.md`,
+    configPath: (n) => `.claude/config-templates/${n}`,
+    rulesFile: "CLAUDE.md",
+    manifestDir: ".claude",
+    sentinelBegin: SENTINEL_BEGIN,
+    sentinelEnd: SENTINEL_END
+  },
+  cursor: {
+    toolId: "cursor",
+    displayName: "Cursor",
+    skillPath: (n) => `.cursor/skills/${n}/SKILL.md`,
+    skillDir: (n) => `.cursor/skills/${n}`,
+    promptPath: (n) => `.cursor/prompts/${n}.md`,
+    configPath: (n) => `.cursor/config-templates/${n}`,
+    rulesFile: ".cursor/rules/10x-course.mdc",
+    manifestDir: ".cursor",
+    sentinelBegin: SENTINEL_BEGIN,
+    sentinelEnd: SENTINEL_END
+  },
+  copilot: {
+    toolId: "copilot",
+    displayName: "GitHub Copilot",
+    skillPath: (n) => `.github/skills/${n}/SKILL.md`,
+    skillDir: (n) => `.github/skills/${n}`,
+    promptPath: (n) => `.github/prompts/${n}.md`,
+    configPath: (n) => `.github/config-templates/${n}`,
+    rulesFile: ".github/copilot-instructions.md",
+    manifestDir: ".github",
+    sentinelBegin: SENTINEL_BEGIN,
+    sentinelEnd: SENTINEL_END
+  },
+  codex: {
+    toolId: "codex",
+    displayName: "Codex CLI",
+    skillPath: (n) => `.agents/skills/${n}/SKILL.md`,
+    skillDir: (n) => `.agents/skills/${n}`,
+    promptPath: (n) => `.agents/prompts/${n}.md`,
+    configPath: (n) => `.agents/config-templates/${n}`,
+    rulesFile: "AGENTS.md",
+    manifestDir: ".agents",
+    sentinelBegin: SENTINEL_BEGIN,
+    sentinelEnd: SENTINEL_END
+  },
+  windsurf: {
+    toolId: "windsurf",
+    displayName: "Windsurf",
+    skillPath: (n) => `.windsurf/skills/${n}/SKILL.md`,
+    skillDir: (n) => `.windsurf/skills/${n}`,
+    promptPath: (n) => `.windsurf/prompts/${n}.md`,
+    configPath: (n) => `.windsurf/config-templates/${n}`,
+    rulesFile: ".windsurfrules",
+    manifestDir: ".windsurf",
+    sentinelBegin: SENTINEL_BEGIN,
+    sentinelEnd: SENTINEL_END
+  },
+  generic: {
+    toolId: "generic",
+    displayName: "Other / Generic",
+    skillPath: (n) => `.ai/skills/${n}/SKILL.md`,
+    skillDir: (n) => `.ai/skills/${n}`,
+    promptPath: (n) => `.ai/prompts/${n}.md`,
+    configPath: (n) => `.ai/config-templates/${n}`,
+    rulesFile: "AGENTS.md",
+    manifestDir: ".ai",
+    sentinelBegin: SENTINEL_BEGIN,
+    sentinelEnd: SENTINEL_END
+  }
+};
+var DEFAULT_TOOL = "claude-code";
+
 // src/commands/doctor.ts
 var EX_CONFIG = 78;
 function registerDoctorCommand(cli) {
-  cli.command("doctor", "Diagnose auth, API, config, and .claude/ state").action(async (options) => {
+  cli.command("doctor", "Diagnose auth, API, config, and tool directory state").action(async (options) => {
     const ctx = resolveContext(options);
     await runDoctor(ctx);
   });
@@ -3714,7 +3795,7 @@ async function runDoctor(ctx) {
   checks.push(await checkApiConnectivity());
   checks.push(checkConfigDirectory());
   checks.push(checkCliVersion());
-  checks.push(checkClaudeDirectory());
+  checks.push(checkToolDirectory());
   const failed = checks.filter((c2) => c2.status === "fail").length;
   const passed = checks.filter((c2) => c2.status === "pass").length;
   const warned = checks.filter((c2) => c2.status === "warn").length;
@@ -3871,36 +3952,39 @@ function checkCliVersion() {
     details: { version: package_default.version }
   };
 }
-function checkClaudeDirectory() {
+function checkToolDirectory() {
   const cwd = process.cwd();
-  const claudeDir = join2(cwd, ".claude");
-  if (!existsSync2(claudeDir)) {
+  const toolId = readToolConfig()?.tool ?? DEFAULT_TOOL;
+  const profile = PROFILES[toolId] ?? PROFILES[DEFAULT_TOOL];
+  const dirName = profile.manifestDir;
+  const toolDir = join2(cwd, dirName);
+  if (!existsSync2(toolDir)) {
     return {
-      name: "claude",
-      label: "Claude",
+      name: "tool-dir",
+      label: profile.displayName,
       status: "fail",
-      message: `.claude/ was not found in ${cwd}.`,
-      hint: "Run '10x doctor' from a project directory that already has a .claude/ folder.",
-      details: { path: claudeDir, exists: false }
+      message: `${dirName}/ was not found in ${cwd}.`,
+      hint: `Run '10x doctor' from a project directory that already has a ${dirName}/ folder.`,
+      details: { path: toolDir, exists: false, tool: toolId }
     };
   }
   try {
-    accessSync(claudeDir, constants.W_OK);
+    accessSync(toolDir, constants.W_OK);
     return {
-      name: "claude",
-      label: "Claude",
+      name: "tool-dir",
+      label: profile.displayName,
       status: "pass",
-      message: `${claudeDir} is writable.`,
-      details: { path: claudeDir, exists: true }
+      message: `${toolDir} is writable.`,
+      details: { path: toolDir, exists: true, tool: toolId }
     };
   } catch (err) {
     return {
-      name: "claude",
-      label: "Claude",
+      name: "tool-dir",
+      label: profile.displayName,
       status: "fail",
-      message: `${claudeDir} is not writable.`,
+      message: `${toolDir} is not writable.`,
       hint: `Fix directory permissions, then run '10x doctor' again. (${err instanceof Error ? err.message : String(err)})`,
-      details: { path: claudeDir, exists: true }
+      details: { path: toolDir, exists: true, tool: toolId }
     };
   }
 }
@@ -4017,73 +4101,6 @@ function isStringArray(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
 
-// src/lib/tool-profile.ts
-var SENTINEL_BEGIN = "<!-- BEGIN @przeprogramowani/10x-cli -->";
-var SENTINEL_END = "<!-- END @przeprogramowani/10x-cli -->";
-var PROFILES = {
-  "claude-code": {
-    toolId: "claude-code",
-    displayName: "Claude Code",
-    skillPath: (n) => `.claude/skills/${n}/SKILL.md`,
-    skillDir: (n) => `.claude/skills/${n}`,
-    promptPath: (n) => `.claude/prompts/${n}.md`,
-    configPath: (n) => `.claude/config-templates/${n}`,
-    rulesFile: "CLAUDE.md",
-    manifestDir: ".claude",
-    sentinelBegin: SENTINEL_BEGIN,
-    sentinelEnd: SENTINEL_END
-  },
-  cursor: {
-    toolId: "cursor",
-    displayName: "Cursor",
-    skillPath: (n) => `.cursor/skills/${n}/SKILL.md`,
-    skillDir: (n) => `.cursor/skills/${n}`,
-    promptPath: (n) => `.cursor/prompts/${n}.md`,
-    configPath: (n) => `.cursor/config-templates/${n}`,
-    rulesFile: ".cursor/rules/10x-course.mdc",
-    manifestDir: ".cursor",
-    sentinelBegin: SENTINEL_BEGIN,
-    sentinelEnd: SENTINEL_END
-  },
-  copilot: {
-    toolId: "copilot",
-    displayName: "GitHub Copilot",
-    skillPath: (n) => `.github/skills/${n}/SKILL.md`,
-    skillDir: (n) => `.github/skills/${n}`,
-    promptPath: (n) => `.github/prompts/${n}.md`,
-    configPath: (n) => `.github/config-templates/${n}`,
-    rulesFile: ".github/copilot-instructions.md",
-    manifestDir: ".github",
-    sentinelBegin: SENTINEL_BEGIN,
-    sentinelEnd: SENTINEL_END
-  },
-  codex: {
-    toolId: "codex",
-    displayName: "Codex CLI",
-    skillPath: (n) => `.agents/skills/${n}/SKILL.md`,
-    skillDir: (n) => `.agents/skills/${n}`,
-    promptPath: (n) => `.agents/prompts/${n}.md`,
-    configPath: (n) => `.agents/config-templates/${n}`,
-    rulesFile: "AGENTS.md",
-    manifestDir: ".agents",
-    sentinelBegin: SENTINEL_BEGIN,
-    sentinelEnd: SENTINEL_END
-  },
-  generic: {
-    toolId: "generic",
-    displayName: "Other / Generic",
-    skillPath: (n) => `.ai/skills/${n}/SKILL.md`,
-    skillDir: (n) => `.ai/skills/${n}`,
-    promptPath: (n) => `.ai/prompts/${n}.md`,
-    configPath: (n) => `.ai/config-templates/${n}`,
-    rulesFile: "AGENTS.md",
-    manifestDir: ".ai",
-    sentinelBegin: SENTINEL_BEGIN,
-    sentinelEnd: SENTINEL_END
-  }
-};
-var DEFAULT_TOOL = "claude-code";
-
 // src/lib/tool-detect.ts
 function detectTools(projectRoot) {
   const hit = (rel) => existsSync4(join4(projectRoot, rel));
@@ -4140,6 +4157,17 @@ function detectTools(projectRoot) {
   } else if (hit("AGENTS.md") && !hit(".ai")) {
     signals.push({ profileId: "codex", confidence: "medium", reason: "AGENTS.md" });
   }
+  if (hit(".windsurf/" + MANIFEST_FILENAME)) {
+    signals.push({
+      profileId: "windsurf",
+      confidence: "strong",
+      reason: ".windsurf/.10x-cli-manifest.json"
+    });
+  } else if (hit(".windsurfrules")) {
+    signals.push({ profileId: "windsurf", confidence: "strong", reason: ".windsurfrules" });
+  } else if (hit(".windsurf")) {
+    signals.push({ profileId: "windsurf", confidence: "medium", reason: ".windsurf/ directory" });
+  }
   if (hit(".ai/" + MANIFEST_FILENAME)) {
     signals.push({
       profileId: "generic",
@@ -4154,7 +4182,7 @@ function detectTools(projectRoot) {
   return rankSignals(signals);
 }
 var CONFIDENCE_ORDER = { strong: 3, medium: 2, weak: 1 };
-var PROFILE_ORDER = ["claude-code", "cursor", "copilot", "codex", "generic"];
+var PROFILE_ORDER = ["claude-code", "cursor", "copilot", "codex", "windsurf", "generic"];
 function rankSignals(signals) {
   return [...signals].sort((a2, b2) => {
     const c2 = CONFIDENCE_ORDER[b2.confidence] - CONFIDENCE_ORDER[a2.confidence];
@@ -4904,7 +4932,10 @@ async function runGet(ctx, ref, options) {
     return;
   }
   verbose(ctx, `fetching lesson ${course}/${parsed.lessonId}`);
-  const result = await fetchLesson(course, parsed.lessonId, auth.access_token, { lang });
+  const result = await fetchLesson(course, parsed.lessonId, auth.access_token, {
+    lang,
+    tool: profile.toolId
+  });
   if (!result.ok) {
     handleLessonError(ctx, result.status, result.code, result.error, result.payload);
   }
@@ -4984,7 +5015,7 @@ async function runPrintMode(ctx, lessonId, course, profile, token, lang, options
     }
   } else {
     verbose(ctx, `fetching lesson ${course}/${lessonId} (filtering by ${options.type})`);
-    const result = await fetchLesson(course, lessonId, token, { lang });
+    const result = await fetchLesson(course, lessonId, token, { lang, tool: profile.toolId });
     if (!result.ok) {
       handleLessonError(ctx, result.status, result.code, result.error, result.payload);
     }

package/package.json

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

package/skills/10x-cli-guide/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: 10x-cli-guide
+description: Invoke this skill when the user asks how to USE the 10x-cli day-to-day — fetching lessons, listing modules, switching AI tools, troubleshooting errors, understanding where artifacts land, or working on a specific OS (Windows, Linux, macOS). Covers commands (get, list, doctor, auth --status/--logout), tool profiles, artifact locations, common errors, and platform-specific tips. Excludes: first-time installation and onboarding (use 10x-cli-setup instead), developing or contributing to 10x-cli source code, and general programming help.
+---
+
+# 10x-cli Daily Usage Guide
+
+This skill helps users work with `@przeprogramowani/10x-cli` after it is already installed and authenticated. If the user has not installed or authenticated yet, hand off to the **10x-cli-setup** skill instead.
+
+## Step 1: Detect the user's environment
+
+Before giving any guidance, gather context silently — run these checks and remember the results. Do not print raw output to the user.
+
+### Operating system
+
+```bash
+echo "$OSTYPE" 2>/dev/null || echo "win32"
+```
+
+Use the result to tailor path separators, shell syntax, and clipboard commands throughout your answers:
+
+| OS | Shell | Home var | Clipboard | Temp dir |
+|----|-------|----------|-----------|----------|
+| macOS (`darwin*`) | zsh / bash | `$HOME` | `pbcopy` | `$TMPDIR` |
+| Linux (`linux-gnu*`) | bash / zsh | `$HOME` | `xclip -selection clipboard` or `xsel --clipboard` | `/tmp` |
+| Windows (`win32` / MSYS / Git Bash) | PowerShell / cmd | `%USERPROFILE%` | `clip.exe` | `%TEMP%` |
+
+### Active AI tool
+
+```bash
+10x doctor --json 2>/dev/null | head -1
+```
+
+Also check which tool profile is configured:
+
+```bash
+cat ~/.config/10x-cli/config.json 2>/dev/null || cat "$APPDATA/10x-cli/config.json" 2>/dev/null || echo "{}"
+```
+
+If the config contains a `"tool"` key, that is the active profile. If not, the default is `claude-code`.
+
+### CLI version
+
+```bash
+10x --version
+```
+
+## Step 2: Answer the user's question using the reference below
+
+Use the environment context from Step 1 to personalize every answer. Always use the OS-appropriate shell syntax, paths, and commands. Never show macOS-specific commands to a Windows user or vice versa.
+
+---
+
+## Command Reference
+
+### `10x get <ref>` — Fetch and apply lesson artifacts
+
+The primary daily command. Fetches a lesson bundle from the API and writes skills, prompts, rules, and config templates to the project directory.
+
+```bash
+10x get m1l1              # Fetch module 1, lesson 1
+10x get m2l3              # Fetch module 2, lesson 3
+10x get m1l1 --dry-run    # Preview what would be written
+10x get m1l1 --tool cursor  # Use a different AI tool profile
+10x get m1l1 --lang pl    # Fetch Polish content
+```
+
+**Filtering artifacts:**
+
+```bash
+10x get m1l1 --type skills                     # Only skills
+10x get m1l1 --type skills --name code-review  # One specific skill
+10x get m1l1 --print --type skills --name code-review  # Print to stdout
+```
+
+**Where artifacts land** (depends on the active tool profile):
+
+| Tool | Skills | Prompts | Rules file | Config templates |
+|------|--------|---------|------------|------------------|
+| Claude Code | `.claude/skills/<name>/SKILL.md` | `.claude/prompts/<name>.md` | `CLAUDE.md` | `.claude/config-templates/<name>` |
+| Cursor | `.cursor/skills/<name>/SKILL.md` | `.cursor/prompts/<name>.md` | `.cursor/rules/10x-course.mdc` | `.cursor/config-templates/<name>` |
+| GitHub Copilot | `.github/skills/<name>/SKILL.md` | `.github/prompts/<name>.md` | `.github/copilot-instructions.md` | `.github/config-templates/<name>` |
+| Codex CLI | `.agents/skills/<name>/SKILL.md` | `.agents/prompts/<name>.md` | `AGENTS.md` | `.agents/config-templates/<name>` |
+| Generic | `.ai/skills/<name>/SKILL.md` | `.ai/prompts/<name>.md` | `AGENTS.md` | `.ai/config-templates/<name>` |
+
+**Re-applying a lesson** overwrites skills and prompts if content changed, updates the rules sentinel block, but never overwrites config templates (they may contain user edits).
+
+**Switching lessons** cleans up artifacts from the previous lesson that are not in the new one, keeps shared artifacts, and adds new ones.
+
+### `10x list [module]` — Browse available content
+
+```bash
+10x list       # Show all modules with lock state
+10x list m1    # Show lessons in module 1
+```
+
+Locked modules show their unlock date. Use this to see what is available before fetching.
+
+### `10x doctor` — Diagnose problems
+
+Runs 5 checks: Auth status, API connectivity, Config directory, CLI version, and tool directory presence.
+
+```bash
+10x doctor          # Human-readable output
+10x doctor --json   # Machine-readable for scripting
+```
+
+Exit code 78 means at least one check failed.
+
+### `10x auth` — Session management
+
+```bash
+10x auth             # Start magic-link login
+10x auth --status    # Check current session
+10x auth --logout    # Clear credentials
+```
+
+Sessions refresh transparently — if a token is near expiry, the next command refreshes it automatically. You only need to re-auth manually if the session has fully expired.
+
+---
+
+## Switching Tools
+
+To change your AI tool (e.g., from Claude Code to Cursor):
+
+```bash
+10x get m1l1 --tool cursor
+```
+
+The CLI will detect that artifacts from the old tool exist and offer two options:
+
+1. **Migrate** (default) — move all artifacts to the new tool's directories, remove the sentinel block from the old rules file.
+2. **Delete** — remove only 10x-managed artifacts from the old tool's directories. Your own files (e.g., `.github/workflows/`) are never touched.
+
+The tool choice is saved in the config file (`~/.config/10x-cli/config.json` on macOS/Linux, `%APPDATA%/10x-cli/config.json` on Windows). Future `get` commands will use the new tool without needing `--tool` again.
+
+---
+
+## Platform-Specific Tips
+
+### Windows
+
+- **Use PowerShell** (not cmd.exe). The CLI outputs ANSI colors and Unicode symbols that render correctly in Windows Terminal + PowerShell but may garble in legacy cmd.
+- **npx works fine**: `npx @przeprogramowani/10x-cli get m1l1` — no global install needed. Node 20+ is the only prerequisite.
+- **Clipboard**: Skills that copy to clipboard use `clip.exe` on Windows. If a skill outputs a clipboard command, it will fall back silently if `clip.exe` is unavailable.
+- **Config location**: `%APPDATA%\10x-cli\config.json` and `%APPDATA%\10x-cli\auth.json`. The CLI creates these automatically.
+- **Path separators**: The CLI uses Node's `path.join()` internally, so forward slashes in command output (like `.claude/skills/code-review/SKILL.md`) work fine on Windows — no need to convert them.
+
+### Linux
+
+- **Clipboard**: Skills use `xclip -selection clipboard` or `xsel --clipboard`. If neither is installed, clipboard operations fail silently. Install with `sudo apt install xclip` (Debian/Ubuntu) or `sudo dnf install xclip` (Fedora).
+- **Config location**: `~/.config/10x-cli/` (respects `$XDG_CONFIG_HOME` if set).
+
+### macOS
+
+- **Clipboard**: Skills use `pbcopy` — works out of the box.
+- **Config location**: `~/.config/10x-cli/`.
+
+---
+
+## Troubleshooting
+
+When the user reports a problem, follow this sequence:
+
+### 1. Run doctor first
+
+```bash
+10x doctor
+```
+
+This catches the most common issues. Read the output and address each failing check.
+
+### 2. Common problems and fixes
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| "You're not signed in" | No auth or expired session | `10x auth` |
+| "Session expired" | Token past expiry and auto-refresh failed | `10x auth` (re-login) |
+| API unreachable / timeout | Network issue or API outage | Check internet; retry in a few minutes |
+| "Module is locked" | Content not yet released | `10x list` to see unlock date |
+| `.claude/` not found (doctor fail) | Running from wrong directory or wrong tool profile | `cd` to project root; check `10x doctor --json` for which tool is configured |
+| "403 Forbidden" on `10x get` | Module locked or no membership | Check `10x list` for module state; verify enrollment |
+| Orphaned artifact prompt on `get` | Switching tools mid-lesson | Choose "migrate" to move files, or "delete" to clean up |
+| Permission denied writing files | Directory not writable | Check directory permissions; on POSIX: `chmod u+w <dir>` |
+
+### 3. Verbose mode for deeper debugging
+
+```bash
+10x get m1l1 --verbose
+10x doctor --verbose
+```
+
+This prints request/response diagnostics to stderr, useful for diagnosing API or network issues.
+
+### 4. Nuclear reset
+
+If config is corrupted:
+
+On macOS/Linux:
+```bash
+rm -rf ~/.config/10x-cli
+10x auth
+```
+
+On Windows (PowerShell):
+```powershell
+Remove-Item -Recurse -Force "$env:APPDATA\10x-cli"
+10x auth
+```
+
+This clears auth and tool preference. The next `10x auth` recreates everything.
+
+---
+
+## Important Principles
+
+- **Answer with the user's OS and tool in mind.** Never show `pbcopy` to a Windows user. Never show `%APPDATA%` to a macOS user.
+- **Run `10x doctor` before speculating.** It catches 80% of issues.
+- **Don't guess command syntax from memory.** If unsure about a flag or behavior, fetch the latest README: `https://raw.githubusercontent.com/przeprogramowani/10x-cli/refs/heads/master/README.md`
+- **Distinguish tool profile issues from CLI issues.** If artifacts land in the wrong directory, it is a tool profile question. If the command itself fails, it is a CLI/auth/network question.