@przeprogramowani/10x-cli 0.2.0 → 0.4.0

package/README.md

@@ -28,9 +28,40 @@ npm install -g @przeprogramowani/10x-cli
 |---------|-------------|
 | `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 `.claude/` |
+| `10x get <ref>` | Fetch a lesson and apply artifacts to your workspace |
 | `10x doctor` | Diagnose auth, API connectivity, and local config |
 
+### `10x get` Flags
+
+| Flag | Description |
+|------|-------------|
+| `--tool <tool>` | AI coding tool: `claude-code`, `cursor`, `copilot`, `codex`, `generic` |
+| `--print` | Output artifact content to stdout instead of writing files |
+| `--type <type>` | Filter by artifact type: `skills`, `prompts`, `rules`, `configs` |
+| `--name <name>` | Filter by artifact name (requires `--type`) |
+| `--dry-run` | Show what would be written without touching the filesystem |
+| `--course <slug>` | Override the course slug (default: `10xdevs3`) |
+
+#### Examples
+
+```bash
+# Fetch full lesson — writes skills, prompts, rules, configs
+10x get m1l1
+
+# Write only skills (skip prompts, rules, configs)
+10x get m1l1 --type skills
+
+# Write a single artifact
+10x get m1l1 --type skills --name code-review
+
+# Print to stdout (pipe-friendly)
+10x get m1l1 --print --type skills --name code-review
+10x get m1l1 --print --type skills --name code-review | pbcopy
+
+# Use with a different AI coding tool
+10x get m1l1 --tool cursor
+```
+
 ### Global Flags
 
 - `--json` — Machine-readable JSON output (auto-detected when piped)
@@ -45,6 +76,20 @@ Lessons are referenced by module and lesson number:
 - `m1l1` — Module 1, Lesson 1
 - `m2l3` — Module 2, Lesson 3
 
+### Multi-Tool Support
+
+On first run, the CLI prompts you to choose your AI coding tool. Artifacts are written to the correct directory for your tool:
+
+| Tool | Directory | Rules file |
+|------|-----------|------------|
+| Claude Code | `.claude/` | `CLAUDE.md` |
+| Cursor | `.cursor/` | `.cursor/rules/10x-course.mdc` |
+| GitHub Copilot | `.github/` | `.github/copilot-instructions.md` |
+| Codex CLI | `.agents/` | `AGENTS.md` |
+| Generic | `.ai/` | `AGENTS.md` |
+
+Override anytime with `--tool <name>`. Your choice is saved in `~/.config/10x-cli/config.json`.
+
 ## Development
 
 ```bash

package/dist/index.mjs

@@ -2271,8 +2271,16 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "@przeprogramowani/10x-cli",
-  version: "0.2.0",
+  version: "0.4.0",
   description: "Open-source CLI for 10xDevs course content",
+  repository: {
+    type: "git",
+    url: "https://github.com/przeprogramowani/10x-cli.git"
+  },
+  homepage: "https://github.com/przeprogramowani/10x-cli",
+  bugs: {
+    url: "https://github.com/przeprogramowani/10x-cli/issues"
+  },
   type: "module",
   bin: {
     "10x": "./dist/index.mjs"
@@ -3053,7 +3061,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);
@@ -3441,7 +3449,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) {
@@ -3456,11 +3464,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({
@@ -3471,8 +3522,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.");
   }
@@ -3486,16 +3538,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 {
@@ -3505,6 +3562,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,
@@ -3518,6 +3582,50 @@ async function fetchLesson(course, lessonId, token, options = {}) {
   }
   return result;
 }
+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");
+  const headerHash = result.responseHeaders.get("X-Bundle-Content-Hash");
+  if (signature && keyIdRaw && headerHash) {
+    const keyId = Number(keyIdRaw);
+    try {
+      verifyBundleSignature(result.rawBody, signature, keyId, headerHash);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        status: 0,
+        code: err instanceof SignatureError ? "signature_error" : "signature_internal_error",
+        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,
+      status: 0,
+      code: "signature_missing",
+      error: "Artifact is missing a signature. The API may be misconfigured or compromised. " + "Do NOT use the content. Report this to the course team."
+    };
+  } else {
+    process.stderr.write(`Warning: artifact is not signed. Signature verification skipped.
+`);
+  }
+  return result;
+}
 async function fetchHealth(options = {}) {
   const timeoutMs = options.timeoutMs ?? 5000;
   const controller = new AbortController;
@@ -4023,6 +4131,7 @@ var CLI_VERSION = package_default.version;
 var DEFAULT_COURSE = "10xdevs3";
 function applyBundle(bundle, projectRoot, options = {}) {
   const dryRun = options.dryRun === true;
+  const partial = options.partial === true;
   const course = options.course ?? DEFAULT_COURSE;
   const profile = options.profile ?? PROFILES[DEFAULT_TOOL];
   const manifestDir = join4(projectRoot, profile.manifestDir);
@@ -4078,7 +4187,7 @@ function applyBundle(bundle, projectRoot, options = {}) {
     }
     return { name: config.name, path: target, action };
   });
-  if (!dryRun) {
+  if (!dryRun && !partial) {
     const removed = computeRemovals(prevManifest, bundle, profile, projectRoot);
     for (const entry of removed.skills)
       rmSync2(entry.path, { recursive: true, force: true });
@@ -4087,7 +4196,7 @@ function applyBundle(bundle, projectRoot, options = {}) {
     for (const entry of removed.configs)
       rmSync2(entry.path, { force: true });
   }
-  if (!dryRun) {
+  if (!dryRun && !partial) {
     const nextManifest = {
       package: CLI_PACKAGE_NAME,
       version: CLI_VERSION,
@@ -4213,9 +4322,13 @@ function isSafeName(name) {
 }
 
 // src/commands/get.ts
+var ARTIFACT_TYPES = ["skills", "prompts", "rules", "configs"];
+function isArtifactType(s) {
+  return ARTIFACT_TYPES.includes(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)").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);
   });
@@ -4225,23 +4338,114 @@ async function runGet(ctx, ref, options) {
   if (!parsed) {
     outputError(ctx, "invalid_lesson_ref", `'${ref}' is not a valid lesson reference.`, ExitCodes.USAGE, "Use the form 'm<module>l<lesson>', for example 'm1l1' or 'm2l3'.");
   }
+  if (options.name && !options.type) {
+    outputError(ctx, "missing_type", "Specify --type when using --name.", ExitCodes.USAGE, "Usage: 10x get m1l1 --type skills --name code-review");
+  }
+  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, 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);
-  const bundle = result.data;
+  const isFiltered = options.type !== undefined;
+  const bundle = filterBundle(ctx, result.data, options);
   const writeResult = applyBundle(bundle, process.cwd(), {
     dryRun: options.dryRun === true,
-    profile
+    profile,
+    partial: isFiltered
+  });
+  renderGetResult(ctx, bundle, writeResult, options.dryRun === true, profile, {
+    language: contentLang ?? lang,
+    languageFallback: isFallback
   });
-  renderGetResult(ctx, bundle, writeResult, options.dryRun === true, profile);
+}
+function filterBundle(ctx, bundle, options) {
+  if (!options.type) {
+    if (options.name) {
+      outputError(ctx, "missing_type", "Specify --type when using --name.", ExitCodes.USAGE, "Usage: 10x get m1l1 --type skills --name code-review");
+    }
+    return bundle;
+  }
+  if (!isArtifactType(options.type)) {
+    outputError(ctx, "invalid_type", `Unknown artifact type '${options.type}'.`, ExitCodes.USAGE, `Supported types: ${ARTIFACT_TYPES.join(", ")}`);
+  }
+  const type = options.type;
+  const empty = {
+    ...bundle,
+    skills: [],
+    prompts: [],
+    rules: [],
+    configs: []
+  };
+  if (options.name) {
+    const match = bundle[type].find((a2) => a2.name === options.name);
+    if (!match) {
+      outputError(ctx, "artifact_not_found", `No ${type} artifact named '${options.name}' in ${bundle.lessonId}.`, ExitCodes.NOT_FOUND, `Available ${type}: ${bundle[type].map((a2) => a2.name).join(", ") || "(none)"}`);
+    }
+    return { ...empty, [type]: [match] };
+  }
+  return { ...empty, [type]: bundle[type] };
+}
+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]");
+  }
+  if (!isArtifactType(options.type)) {
+    outputError(ctx, "invalid_type", `Unknown artifact type '${options.type}'.`, ExitCodes.USAGE, `Supported types: ${ARTIFACT_TYPES.join(", ")}`);
+  }
+  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, { lang });
+    if (!result.ok) {
+      handleLessonError(ctx, result.status, result.code, result.error, result.payload);
+    }
+    if (ctx.json) {
+      output(ctx, "", result.data);
+    } else {
+      process.stdout.write(result.data.content);
+    }
+  } else {
+    verbose(ctx, `fetching lesson ${course}/${lessonId} (filtering by ${options.type})`);
+    const result = await fetchLesson(course, lessonId, token, { lang });
+    if (!result.ok) {
+      handleLessonError(ctx, result.status, result.code, result.error, result.payload);
+    }
+    const artifacts = result.data[options.type];
+    if (ctx.json) {
+      output(ctx, "", artifacts);
+    } else {
+      const contents = artifacts.map((a2) => a2.content);
+      process.stdout.write(contents.join(`
+---
+`));
+    }
+  }
 }
 function handleLessonError(ctx, status, code, error, payload) {
   verbose(ctx, `lesson fetch failed: status=${status} code=${code}`);
@@ -4276,13 +4480,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,
@@ -4422,7 +4628,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;
@@ -4440,6 +4647,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,7 +1,15 @@
 {
   "name": "@przeprogramowani/10x-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Open-source CLI for 10xDevs course content",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/przeprogramowani/10x-cli.git"
+  },
+  "homepage": "https://github.com/przeprogramowani/10x-cli",
+  "bugs": {
+    "url": "https://github.com/przeprogramowani/10x-cli/issues"
+  },
   "type": "module",
   "bin": {
     "10x": "./dist/index.mjs"