@przeprogramowani/10x-cli 0.3.0 → 0.5.0

package/README.md

@@ -13,6 +13,26 @@ npm install -g @przeprogramowani/10x-cli
 # https://github.com/przeprogramowani/10x-cli/releases
 ```
 
+## Agentic Installation
+
+Let your AI coding agent handle the setup. This repo ships a [`10x-cli-setup`](skills/10x-cli-setup/SKILL.md) skill that walks your agent through installing, authenticating, and configuring the CLI — all driven by the latest README.
+
+Install the skill with [skills.sh](https://skills.sh):
+
+```bash
+# Add the skill to your current project (symlinked)
+npx skills add przeprogramowani/10x-cli
+
+# Or install globally so it's available in every project
+npx skills add przeprogramowani/10x-cli -g
+
+# Target a specific agent
+npx skills add przeprogramowani/10x-cli -a claude-code
+npx skills add przeprogramowani/10x-cli -a cursor
+```
+
+Once installed, just tell your agent to **set up 10x-cli** and it will pick up the skill automatically.
+
 ## Quick Start
 
 ```bash

package/dist/index.mjs

@@ -2271,7 +2271,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "@przeprogramowani/10x-cli",
-  version: "0.3.0",
+  version: "0.5.0",
   description: "Open-source CLI for 10xDevs course content",
   repository: {
     type: "git",
@@ -2287,6 +2287,7 @@ var package_default = {
   },
   files: [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -3061,7 +3062,7 @@ async function request(method, path, body, options = {}) {
       payload
     };
   }
-  return { ok: true, status: response.status, data: parsed, responseHeaders: response.headers };
+  return { ok: true, status: response.status, data: parsed, responseHeaders: response.headers, rawBody: text };
 }
 function apiGet(path, options = {}) {
   return request("GET", path, undefined, options);
@@ -3449,7 +3450,7 @@ import { existsSync as existsSync2, accessSync, constants } from "node:fs";
 import { join as join2 } from "node:path";
 
 // src/lib/signing.ts
-import { createPublicKey, verify } from "node:crypto";
+import { createHash, createPublicKey, verify } from "node:crypto";
 
 class SignatureError extends Error {
   constructor(message) {
@@ -3464,11 +3465,54 @@ var KEYSET = [
   }
 ];
 var REQUIRE_SIGNATURES = true;
-function verifyBundleSignature(responseBody, signature, keyId) {
-  const key = KEYSET.find((k3) => k3.keyId === keyId);
+function loadEffectiveKeyset() {
+  const override = process.env["BUNDLE_PUBLIC_KEYSET"];
+  if (!override)
+    return KEYSET;
+  const apiBase = process.env["API_BASE_URL"];
+  if (!apiBase)
+    return KEYSET;
+  let hostname;
+  try {
+    hostname = new URL(apiBase).hostname;
+  } catch {
+    return KEYSET;
+  }
+  if (hostname !== "localhost" && hostname !== "127.0.0.1") {
+    return KEYSET;
+  }
+  try {
+    const parsed = JSON.parse(override);
+    if (!Array.isArray(parsed) || parsed.length === 0)
+      return KEYSET;
+    for (const k3 of parsed) {
+      if (typeof k3.keyId !== "number" || typeof k3.publicKey !== "string") {
+        return KEYSET;
+      }
+    }
+    return parsed;
+  } catch {
+    return KEYSET;
+  }
+}
+function sha256Hex(body) {
+  return createHash("sha256").update(body).digest("hex");
+}
+function canonicalSigningString(keyId, hashHex) {
+  return `v1:${keyId}:${hashHex}`;
+}
+function verifyBundleSignature(rawBody, signature, keyId, headerHash) {
+  verifyBundleSignatureWithKeyset(rawBody, signature, keyId, headerHash, loadEffectiveKeyset());
+}
+function verifyBundleSignatureWithKeyset(rawBody, signature, keyId, headerHash, keyset) {
+  const key = keyset.find((k3) => k3.keyId === keyId);
   if (!key) {
     throw new SignatureError(`Unknown signing key (key_id=${keyId}). Update your CLI: npm update -g @przeprogramowani/10x-cli`);
   }
+  const computedHash = sha256Hex(rawBody);
+  if (computedHash !== headerHash) {
+    throw new SignatureError(`Bundle content hash mismatch (header=${headerHash.slice(0, 12)}…, computed=${computedHash.slice(0, 12)}…). ` + "The bundle may have been tampered with in transit. Do NOT use the content.");
+  }
   let pubKey;
   try {
     pubKey = createPublicKey({
@@ -3479,8 +3523,9 @@ function verifyBundleSignature(responseBody, signature, keyId) {
   } catch {
     throw new SignatureError("Failed to load the signing public key. Your CLI binary may be corrupted — reinstall it.");
   }
+  const canonical = canonicalSigningString(keyId, computedHash);
   const sig = Buffer.from(signature, "base64");
-  const valid = verify(null, Buffer.from(responseBody), pubKey, sig);
+  const valid = verify(null, Buffer.from(canonical), pubKey, sig);
   if (!valid) {
     throw new SignatureError("Bundle signature verification failed — the bundle may have been tampered with. " + "Do NOT use the content. Report this to the course team.");
   }
@@ -3494,16 +3539,21 @@ function fetchModuleDetail(course, module, token, options = {}) {
   return apiGet(`/api/modules/${encodeURIComponent(course)}/${module}`, { token, signal: options.signal });
 }
 async function fetchLesson(course, lessonId, token, options = {}) {
-  const result = await apiGet(`/api/lessons/${encodeURIComponent(course)}/${encodeURIComponent(lessonId)}`, { token, signal: options.signal });
+  const params = new URLSearchParams;
+  if (options.lang)
+    params.set("lang", options.lang);
+  const qs = params.toString();
+  const path = `/api/lessons/${encodeURIComponent(course)}/${encodeURIComponent(lessonId)}${qs ? `?${qs}` : ""}`;
+  const result = await apiGet(path, { token, signal: options.signal });
   if (!result.ok)
     return result;
   const signature = result.responseHeaders.get("X-Bundle-Signature");
   const keyIdRaw = result.responseHeaders.get("X-Bundle-Key-Id");
-  if (signature && keyIdRaw) {
+  const headerHash = result.responseHeaders.get("X-Bundle-Content-Hash");
+  if (signature && keyIdRaw && headerHash) {
     const keyId = Number(keyIdRaw);
-    const responseBody = JSON.stringify(result.data);
     try {
-      verifyBundleSignature(responseBody, signature, keyId);
+      verifyBundleSignature(result.rawBody, signature, keyId, headerHash);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       return {
@@ -3513,6 +3563,13 @@ async function fetchLesson(course, lessonId, token, options = {}) {
         error: message
       };
     }
+  } else if (signature || keyIdRaw || headerHash) {
+    return {
+      ok: false,
+      status: 0,
+      code: "signature_error",
+      error: "Bundle signing headers are incomplete (expected X-Bundle-Signature, X-Bundle-Key-Id, and X-Bundle-Content-Hash together). " + "The API may be misconfigured. Do NOT use the content. Report this to the course team."
+    };
   } else if (REQUIRE_SIGNATURES) {
     return {
       ok: false,
@@ -3528,17 +3585,19 @@ async function fetchLesson(course, lessonId, token, options = {}) {
 }
 async function fetchArtifact(course, lessonId, type, name, tool, token, options = {}) {
   const params = new URLSearchParams({ tool });
+  if (options.lang)
+    params.set("lang", options.lang);
   const path = `/api/artifacts/${encodeURIComponent(course)}/${encodeURIComponent(lessonId)}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?${params}`;
   const result = await apiGet(path, { token, signal: options.signal });
   if (!result.ok)
     return result;
   const signature = result.responseHeaders.get("X-Bundle-Signature");
   const keyIdRaw = result.responseHeaders.get("X-Bundle-Key-Id");
-  if (signature && keyIdRaw) {
+  const headerHash = result.responseHeaders.get("X-Bundle-Content-Hash");
+  if (signature && keyIdRaw && headerHash) {
     const keyId = Number(keyIdRaw);
-    const responseBody = JSON.stringify(result.data);
     try {
-      verifyBundleSignature(responseBody, signature, keyId);
+      verifyBundleSignature(result.rawBody, signature, keyId, headerHash);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       return {
@@ -3548,6 +3607,13 @@ async function fetchArtifact(course, lessonId, type, name, tool, token, options
         error: message
       };
     }
+  } else if (signature || keyIdRaw || headerHash) {
+    return {
+      ok: false,
+      status: 0,
+      code: "signature_error",
+      error: "Artifact signing headers are incomplete (expected X-Bundle-Signature, X-Bundle-Key-Id, and X-Bundle-Content-Hash together). " + "The API may be misconfigured. Do NOT use the content. Report this to the course team."
+    };
   } else if (REQUIRE_SIGNATURES) {
     return {
       ok: false,
@@ -4263,7 +4329,7 @@ function isArtifactType(s) {
 }
 var DEFAULT_COURSE2 = "10xdevs3";
 function registerGetCommand(cli) {
-  cli.command("get <ref>", "Fetch and apply a lesson pack").option("--dry-run", "Show what would be written without touching the filesystem").option("--course <course>", "Override the course slug (default: 10xdevs3)").option("--tool <tool>", "AI coding tool (claude-code, cursor, copilot, codex, generic)").option("--print", "Print artifact content to stdout instead of writing to files").option("--type <type>", "Artifact type filter: skills, prompts, rules, configs").option("--name <name>", "Artifact name filter (requires --type)").action(async (ref, options) => {
+  cli.command("get <ref>", "Fetch and apply a lesson pack").option("--dry-run", "Show what would be written without touching the filesystem").option("--course <course>", "Override the course slug (default: 10xdevs3)").option("--tool <tool>", "AI coding tool (claude-code, cursor, copilot, codex, generic)").option("--print", "Print artifact content to stdout instead of writing to files").option("--type <type>", "Artifact type filter: skills, prompts, rules, configs").option("--name <name>", "Artifact name filter (requires --type)").option("--lang <lang>", "Content language: en (default) or pl").action(async (ref, options) => {
     const ctx = resolveContext(options);
     await runGet(ctx, ref, options);
   });
@@ -4279,18 +4345,32 @@ async function runGet(ctx, ref, options) {
   if (options.type && !isArtifactType(options.type)) {
     outputError(ctx, "invalid_type", `Unknown artifact type '${options.type}'.`, ExitCodes.USAGE, `Supported types: ${ARTIFACT_TYPES.join(", ")}`);
   }
+  const SUPPORTED_LANGS = ["en", "pl"];
+  if (options.lang && !SUPPORTED_LANGS.includes(options.lang)) {
+    outputError(ctx, "invalid_lang", `Unknown language '${options.lang}'.`, ExitCodes.USAGE, `Supported languages: ${SUPPORTED_LANGS.join(", ")}`);
+  }
   const auth = await requireAuth(ctx);
   const course = options.course ?? DEFAULT_COURSE2;
   const profile = await resolveToolProfile(options.tool);
+  const lang = options.lang ?? readToolConfig()?.lang ?? "en";
+  if (options.lang) {
+    const existing = readToolConfig();
+    saveToolConfig({ tool: existing?.tool ?? profile.toolId, lang: options.lang });
+  }
   if (options.print) {
-    await runPrintMode(ctx, parsed.lessonId, course, profile, auth.access_token, options);
+    await runPrintMode(ctx, parsed.lessonId, course, profile, auth.access_token, lang, options);
     return;
   }
   verbose(ctx, `fetching lesson ${course}/${parsed.lessonId}`);
-  const result = await fetchLesson(course, parsed.lessonId, auth.access_token);
+  const result = await fetchLesson(course, parsed.lessonId, auth.access_token, { lang });
   if (!result.ok) {
     handleLessonError(ctx, result.status, result.code, result.error, result.payload);
   }
+  const contentLang = result.responseHeaders.get("X-Content-Language");
+  const isFallback = result.responseHeaders.get("X-Content-Fallback") === "true";
+  if (isFallback && contentLang) {
+    verbose(ctx, `${lang.toUpperCase()} not available for ${parsed.lessonId}, showing ${contentLang.toUpperCase()}.`);
+  }
   const orphanWarning = detectOrphanedArtifacts(process.cwd(), profile);
   if (orphanWarning)
     verbose(ctx, orphanWarning);
@@ -4301,7 +4381,10 @@ async function runGet(ctx, ref, options) {
     profile,
     partial: isFiltered
   });
-  renderGetResult(ctx, bundle, writeResult, options.dryRun === true, profile);
+  renderGetResult(ctx, bundle, writeResult, options.dryRun === true, profile, {
+    language: contentLang ?? lang,
+    languageFallback: isFallback
+  });
 }
 function filterBundle(ctx, bundle, options) {
   if (!options.type) {
@@ -4330,7 +4413,7 @@ function filterBundle(ctx, bundle, options) {
   }
   return { ...empty, [type]: bundle[type] };
 }
-async function runPrintMode(ctx, lessonId, course, profile, token, options) {
+async function runPrintMode(ctx, lessonId, course, profile, token, lang, options) {
   if (!options.type) {
     outputError(ctx, "missing_type", "Specify --type for --print mode.", ExitCodes.USAGE, "Usage: 10x get m1l1 --print --type skills [--name code-review]");
   }
@@ -4339,7 +4422,7 @@ async function runPrintMode(ctx, lessonId, course, profile, token, options) {
   }
   if (options.name) {
     verbose(ctx, `fetching artifact ${course}/${lessonId}/${options.type}/${options.name}`);
-    const result = await fetchArtifact(course, lessonId, options.type, options.name, profile.toolId, token);
+    const result = await fetchArtifact(course, lessonId, options.type, options.name, profile.toolId, token, { lang });
     if (!result.ok) {
       handleLessonError(ctx, result.status, result.code, result.error, result.payload);
     }
@@ -4350,7 +4433,7 @@ async function runPrintMode(ctx, lessonId, course, profile, token, options) {
     }
   } else {
     verbose(ctx, `fetching lesson ${course}/${lessonId} (filtering by ${options.type})`);
-    const result = await fetchLesson(course, lessonId, token);
+    const result = await fetchLesson(course, lessonId, token, { lang });
     if (!result.ok) {
       handleLessonError(ctx, result.status, result.code, result.error, result.payload);
     }
@@ -4398,13 +4481,15 @@ function handleLessonError(ctx, status, code, error, payload) {
   }
   outputError(ctx, code || "lesson_fetch_failed", "Failed to fetch the lesson bundle.", ExitCodes.ERROR, error ? `Server said: ${error}` : undefined);
 }
-function renderGetResult(ctx, bundle, writeResult, dryRun, profile) {
+function renderGetResult(ctx, bundle, writeResult, dryRun, profile, langMeta = { language: "en", languageFallback: false }) {
   if (ctx.json) {
     output(ctx, "", {
       lessonId: bundle.lessonId,
       title: bundle.title,
       summary: bundle.summary,
       tool: profile.toolId,
+      language: langMeta.language,
+      languageFallback: langMeta.languageFallback,
       dry_run: dryRun,
       writes: {
         skills: writeResult.skills,
@@ -4544,7 +4629,8 @@ function renderModuleDetail(ctx, module) {
         lessonId: l2.lessonId,
         lesson: l2.lesson,
         title: l2.title,
-        summary: l2.summary
+        summary: l2.summary,
+        availableLanguages: l2.availableLanguages ?? ["en"]
       }))
     });
     return;
@@ -4562,6 +4648,11 @@ function renderModuleDetail(ctx, module) {
         lines.push(`      ${l2.summary}`);
     }
   }
+  const hasMultiLang = module.lessons.some((l2) => l2.availableLanguages && l2.availableLanguages.length > 1);
+  if (hasMultiLang) {
+    lines.push("");
+    lines.push("Language variants available. Use --lang pl to fetch Polish content.");
+  }
   output(ctx, lines.join(`
 `), undefined);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@przeprogramowani/10x-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Open-source CLI for 10xDevs course content",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

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

@@ -0,0 +1,53 @@
+---
+name: 10x-cli-setup
+description: ALWAYS invoke this skill when the user mentions 10x-cli, @przeprogramowani/10x-cli, the 10xDevs CLI, or the 10xDevs course environment in a setup context. This skill fetches the live README — Claude does not know 10x-cli's current install steps without it. Applies to: installing, updating, reconfiguring for different AI tools (Cursor, Copilot, Claude Code), permission/npm errors, authentication, and onboarding after 10xDevs enrollment. Excludes: developing 10x-cli source code, contributing to the repo, building similar CLIs, or general project setup.
+---
+
+# 10x-cli Setup
+
+This skill sets up the `@przeprogramowani/10x-cli` on the user's machine. The core principle is simple: **the README is the single source of truth**. The CLI evolves — version requirements change, new install methods appear, commands get updated. Rather than hardcoding any of that here, this skill tells you *how to work*, and the README tells you *what to do*.
+
+## Step 1: Check if the CLI is already installed
+
+Before anything else, check the current state:
+
+```bash
+10x --version 2>/dev/null || echo "NOT_INSTALLED"
+```
+
+- If a version is printed, the CLI is already installed. Tell the user and ask if they want to update, reconfigure, or troubleshoot.
+- If not installed, proceed to Step 2.
+
+This avoids wasting time on prerequisites when the user might just need a config change or re-auth.
+
+## Step 2: Fetch the latest README
+
+Retrieve the current README from GitHub — this is the authoritative source for all install steps, prerequisites, commands, and tool configurations:
+
+```
+URL: https://raw.githubusercontent.com/przeprogramowani/10x-cli/refs/heads/master/README.md
+```
+
+Use WebFetch or `curl -sL` to get it. If the fetch fails, tell the user and stop — don't guess at install steps from memory, because they may be outdated.
+
+## Step 3: Build a plan from the README and execute it
+
+Read the fetched README and construct a step-by-step setup plan from it. The README contains everything needed: prerequisites, install commands, auth flow, available commands, and tool-specific configuration. Your job is to translate the README into actionable steps for the user's specific situation.
+
+The general flow from the README is:
+1. **Prerequisites** — whatever the README says is required (runtime version, package manager, etc.). Check each one and stop if something is missing.
+2. **Install** — use the install method described in the README. Verify it worked.
+3. **Authenticate** — the README describes the auth command and flow. Note: auth is interactive (magic-link email), so the user may need to run it themselves via `! 10x auth` if the shell doesn't support input.
+4. **Verify** — the README lists a diagnostic command. Run it and review the output with the user.
+5. **Explore** — show the user how to browse and fetch content using the commands from the README.
+6. **Tool configuration** — if the user mentioned a specific AI tool (Claude Code, Cursor, etc.), use the README's multi-tool support section to configure it. If not, explain the options and let them choose.
+
+Do not hardcode specific version numbers, command flags, or directory paths — read them from the README. This way the skill stays correct even when the CLI changes.
+
+## Important principles
+
+- **README over memory.** If you think you know a command or requirement, but the fetched README says something different, follow the README. Always.
+- **Check before installing.** Step 1 exists for a reason — don't reinstall what's already there.
+- **Be interactive.** Confirm with the user before installing global packages or modifying their system. Ask before running `sudo`.
+- **Diagnose before fixing.** If something fails, read the error and the README's guidance before suggesting a fix. Don't just retry blindly.
+- **Stay focused on end-user setup.** This skill is about installing and configuring the published CLI package, not about development/contributing workflows.