reflex-agent 0.2.1

package/dist/lib/reflex/walker.js

@@ -0,0 +1,55 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { IgnoreStack } from "./ignore.js";
+/**
+ * Walk `root` honoring nested `.reflexignore` files and a default prune list.
+ * Yields both directories and files so callers can drive per-dir analysis.
+ */
+export async function* walk(root, options = {}) {
+    const { maxDepth = Infinity, followSymlinks = false } = options;
+    const rootAbs = path.resolve(root);
+    const initialStack = await IgnoreStack.create(rootAbs);
+    yield { abs: rootAbs, rel: ".", isDir: true };
+    yield* descend(rootAbs, rootAbs, initialStack, 0, maxDepth, followSymlinks);
+}
+async function* descend(root, dir, stack, depth, maxDepth, followSymlinks) {
+    if (depth >= maxDepth)
+        return;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+        const abs = path.join(dir, e.name);
+        if (stack.ignores(abs))
+            continue;
+        const isSymlink = e.isSymbolicLink();
+        if (isSymlink && !followSymlinks)
+            continue;
+        const isDir = e.isDirectory() || (isSymlink && (await isLinkedDir(abs)));
+        const rel = posixRel(root, abs);
+        yield { abs, rel, isDir };
+        if (isDir) {
+            const child = await stack.enter(abs);
+            yield* descend(root, abs, child, depth + 1, maxDepth, followSymlinks);
+        }
+    }
+}
+async function isLinkedDir(abs) {
+    try {
+        const s = await fs.stat(abs);
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function posixRel(root, abs) {
+    const r = path.relative(root, abs);
+    return r.split(path.sep).join("/");
+}
+//# sourceMappingURL=walker.js.map

package/dist/lib/reflex/walker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walker.js","sourceRoot":"","sources":["../../../lib/reflex/walker.ts"],"names":[],"mappings":"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"}

package/next.config.ts

@@ -0,0 +1,33 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // Allow server components/actions in our local app to spawn child processes
+  // and interact with the local filesystem.
+  serverExternalPackages: [
+    "chokidar",
+    "execa",
+    "esbuild",
+    "sharp",
+    "@tailwindcss/node",
+    "@tailwindcss/oxide",
+    "tailwindcss",
+    "lightningcss",
+  ],
+  // The shared `lib/reflex/` modules use `.js` extensions in their imports
+  // (required by Node's NodeNext resolver for the CLI build). Tell webpack
+  // and Turbopack to fall back to `.ts`/`.tsx` when resolving them.
+  turbopack: {
+    resolveExtensions: [".tsx", ".ts", ".jsx", ".js", ".json"],
+    resolveAlias: {},
+  },
+  webpack: (config) => {
+    config.resolve = config.resolve ?? {};
+    config.resolve.extensionAlias = {
+      ".js": [".ts", ".tsx", ".js"],
+      ".jsx": [".tsx", ".jsx"],
+    };
+    return config;
+  },
+};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "reflex-agent",
+  "version": "0.2.1",
+  "private": false,
+  "description": "Local-first knowledge base built by an agent over a chosen directory.",
+  "license": "MIT",
+  "author": "legostin",
+  "homepage": "https://github.com/legostin/reflex-agent#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/legostin/reflex-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/legostin/reflex-agent/issues"
+  },
+  "type": "module",
+  "bin": {
+    "reflex": "./dist/bin/cli.js"
+  },
+  "files": [
+    "dist",
+    ".next",
+    "next.config.ts",
+    "packages/utilities",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "next dev -p 3210",
+    "start": "next start -p 3210",
+    "build": "next build && pnpm run build:cli",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.cli.json --noEmit",
+    "prepack": "node -e \"require('fs').rmSync('.next/cache', { recursive: true, force: true })\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.29.2",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openai/codex-sdk": "0.133.0",
+    "@radix-ui/react-scroll-area": "^1",
+    "@radix-ui/react-separator": "^1",
+    "@radix-ui/react-slot": "^1",
+    "@radix-ui/react-tabs": "^1",
+    "@tailwindcss/node": "^4.3.0",
+    "@tailwindcss/postcss": "^4",
+    "@tailwindcss/typography": "^0.5.19",
+    "chokidar": "^4",
+    "class-variance-authority": "^0.7",
+    "clsx": "^2",
+    "commander": "^14",
+    "esbuild": "^0.28.0",
+    "execa": "^9",
+    "gray-matter": "^4.0.3",
+    "highlight.js": "^11.11.1",
+    "ignore": "^7",
+    "lucide-react": "^0.475",
+    "mermaid": "^11.15.0",
+    "next": "^15",
+    "next-themes": "^0.4.6",
+    "radix-ui": "^1.4.3",
+    "react": "^19",
+    "react-dom": "^19",
+    "react-markdown": "^9",
+    "rehype-highlight": "^7.0.2",
+    "remark-gfm": "^4",
+    "server-only": "^0.0.1",
+    "sharp": "^0.34.5",
+    "sonner": "^1",
+    "tailwind-merge": "^2",
+    "tailwindcss": "^4",
+    "tw-animate-css": "^1",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "typescript": "^6"
+  }
+}

package/packages/utilities/learn-anything/README.md

@@ -0,0 +1,41 @@
+# 🎓 Изучи что угодно
+
+Универсальный AI-наставник. Введи тему → агент задаёт 2-4 уточняющих вопроса (про уровень, цель, время, формат) → собирает программу 5-9 модулей → каждый модуль с длинной статьёй, видео, иллюстрациями, схемами (mermaid), тестом, домашкой и интерактивным тренажёром на canvas.
+
+## Возможности
+
+- **Wizard в агентном режиме** — вопросы НЕ хардкоженные, агент сам решает что важно спросить под конкретную тему. «Хочу научиться рисовать акварелью» и «Хочу выучить Python» приведут к разным вопросам.
+- **Программа курса** — генерируется с целями и оценкой времени.
+- **Модуль = статья 800-2000 слов** + видео (YouTube) + ссылки на источники + изображения (CC) + mermaid-схемы + 3-5 домашних заданий.
+- **Тест** — 5-7 multiple-choice вопросов сгенерированных из статьи, мгновенная проверка с объяснениями.
+- **Прогресс** — отметка пройденности + результат теста, сохраняется в KB.
+- **Объяснить выделенное** — выдели любой кусок статьи → агент даст подробное объяснение с примерами.
+- **Тренажёр** — агент пишет standalone HTML/JS/canvas под идею (или сам предложит идею), Reflex рендерит в sandboxed iframe.
+
+## KB-схемы
+
+- `course` — корень курса: `meta.courseId`, `meta.topic`, `meta.modules` (JSON), `meta.progress` (JSON), `meta.wizardAnswers` (JSON), `meta.createdAt`.
+- `course-module` — материал модуля: `meta.courseId`, `meta.moduleId`, JSON-поля `videos`/`links`/`images`/`diagrams`/`homework`, body = статья.
+- `course-trainer` — HTML тренажёра в `meta.html` (capped ≈60KB).
+- `course-note` — пользовательские заметки в модуле (опц., пока не используется).
+
+## Server actions
+
+- `tutorAsk({topic, history, forceFinish?})` — следующий вопрос wizard или `{done:true}`.
+- `generateOutline({topic, history})` — программа курса + сохранение KB.
+- `buildModule({courseId, moduleId, moduleTitle, moduleObjective, topic})` — материал модуля.
+- `generateQuiz({moduleTitle, moduleObjective, article})` — тест.
+- `explainSelection({selection, context, topic, moduleTitle})` — глубокое объяснение фрагмента.
+- `generateTrainer({courseId, moduleId, moduleTitle, moduleObjective, prompt?})` — HTML тренажёр.
+- `refreshCourseCard()` — обновление dashboard-карточки (число активных курсов + средний прогресс).
+
+## Разрешения
+
+`llm.chat/quick`, `kb.read/write` для своих kinds, `fs.sandbox` (для будущего кэша), `web.fetch` с whitelist (wikipedia, mdn, youtube, ...), `web.search`, `audit.write`, `workers.enabled`, `agent.invoke`.
+
+## Ограничения v0.1
+
+- Картинки не качаются локально (используются URL'ы CC-источников); подписаны в whitelist.
+- Mermaid-схемы рендерятся как code-block; embed-рендер придёт в v0.2.
+- Тренажёры в `srcdoc` iframe — без доступа к host RPC (только клиентский JS+canvas).
+- Прогресс хранится в frontmatter курса; кэш на mtime ещё не оптимизирован.

package/packages/utilities/learn-anything/actions/_json.ts

@@ -0,0 +1,191 @@
+/**
+ * Resilient JSON extraction from LLM/agent output.
+ *
+ * Strategies tried in order:
+ *   1. Strip ```json/``` fences then JSON.parse the whole content.
+ *   2. Find the outermost balanced `{...}` block via bracket-counter.
+ *   3. Last-resort greedy `/\{[\s\S]*\}/`.
+ *
+ * Returns `null` if every strategy fails — callers usually retry the
+ * LLM call once with a stricter "JSON only, no markdown" prompt.
+ */
+export function extractJson<T = unknown>(raw: string): T | null {
+  if (!raw || typeof raw !== "string") return null;
+  const candidates: string[] = [];
+
+  // Strategy 1: strip outer fences.
+  const fence = /```(?:json)?\s*([\s\S]*?)\s*```/.exec(raw);
+  if (fence) candidates.push(fence[1]!.trim());
+
+  // Strategy 2: balanced-brace scan from first `{`.
+  const start = raw.indexOf("{");
+  if (start >= 0) {
+    let depth = 0;
+    let inStr = false;
+    let escape = false;
+    for (let i = start; i < raw.length; i++) {
+      const ch = raw[i]!;
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escape = true;
+        continue;
+      }
+      if (ch === '"') {
+        inStr = !inStr;
+        continue;
+      }
+      if (inStr) continue;
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          candidates.push(raw.slice(start, i + 1));
+          break;
+        }
+      }
+    }
+  }
+
+  // Strategy 3: greedy fallback.
+  const greedy = /\{[\s\S]*\}/.exec(raw);
+  if (greedy) candidates.push(greedy[0]);
+
+  for (const c of candidates) {
+    try {
+      return JSON.parse(c) as T;
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Short snippet of an agent response, for inclusion in error toasts so
+ * the user can see what went wrong without us shipping the full reply.
+ */
+export function snippet(s: string, max = 240): string {
+  if (!s) return "(пусто)";
+  const trimmed = s.trim();
+  if (trimmed.length <= max) return trimmed;
+  return trimmed.slice(0, max) + "…";
+}
+
+/**
+ * Self-correcting agent loop for JSON-shaped responses.
+ *
+ *   • Up to `maxAttempts` LLM calls (default 4).
+ *   • On parse/validation failure we don't just say "try again" — we
+ *     hand the LLM its own bad answer + a strict format reminder, and
+ *     ask it to FIRST diagnose what was wrong (one phrase) THEN return
+ *     the corrected JSON. The diagnosis is throwaway; only the JSON is
+ *     parsed. Single round-trip per attempt.
+ *   • `validate` is the gatekeeper — return non-null when the parsed
+ *     payload satisfies the caller's structural needs.
+ *
+ * Returns either the validated value with attempt count, or a
+ * structured failure with the last raw text for diagnostics.
+ */
+export interface JsonAgentArgs<T> {
+  /** Initial prompt — should already include the JSON-only instruction. */
+  prompt: string;
+  /** LLM caller (e.g. (p) => reflex.agent.invoke({prompt: p})). */
+  invoke: (prompt: string) => Promise<{ text?: string }>;
+  /** Returns the validated value, or null if shape is wrong / empty. */
+  validate: (parsed: unknown) => T | null;
+  /** Default 4. The LLM call is the slow part — we cap to avoid runaways. */
+  maxAttempts?: number;
+  /** Optional one-line description of the expected shape; surfaces in
+   *  the reflection prompt verbatim. */
+  shapeHint?: string;
+}
+
+export interface JsonAgentSuccess<T> {
+  ok: true;
+  value: T;
+  attempts: number;
+}
+
+export interface JsonAgentFailure {
+  ok: false;
+  attempts: number;
+  lastText: string;
+  /** Why we gave up — "no-json" / "invalid-shape" / "empty-result". */
+  reason: "no-json" | "invalid-shape" | "empty-result";
+}
+
+export async function callJsonAgent<T>(
+  args: JsonAgentArgs<T>,
+): Promise<JsonAgentSuccess<T> | JsonAgentFailure> {
+  const max = Math.max(1, args.maxAttempts ?? 4);
+  let lastText = "";
+  let lastReason: JsonAgentFailure["reason"] = "no-json";
+
+  for (let attempt = 1; attempt <= max; attempt++) {
+    const prompt =
+      attempt === 1
+        ? args.prompt
+        : buildReflectionPrompt(args.prompt, lastText, lastReason, args.shapeHint, attempt);
+
+    const r = await args.invoke(prompt);
+    lastText = r.text ?? "";
+    const json = extractJson<unknown>(lastText);
+    if (!json) {
+      lastReason = "no-json";
+      continue;
+    }
+    const validated = args.validate(json);
+    if (validated == null) {
+      // Distinguish empty vs malformed for the reflection prompt.
+      lastReason = isEmptyShape(json) ? "empty-result" : "invalid-shape";
+      continue;
+    }
+    return { ok: true, value: validated, attempts: attempt };
+  }
+  return { ok: false, attempts: max, lastText, reason: lastReason };
+}
+
+function isEmptyShape(v: unknown): boolean {
+  if (v == null) return true;
+  if (Array.isArray(v)) return v.length === 0;
+  if (typeof v === "object") return Object.keys(v as object).length === 0;
+  return false;
+}
+
+function buildReflectionPrompt(
+  original: string,
+  lastText: string,
+  reason: JsonAgentFailure["reason"],
+  shape: string | undefined,
+  attempt: number,
+): string {
+  const reasonLine =
+    reason === "no-json"
+      ? "Твой предыдущий ответ нельзя было распарсить как JSON (вероятно: markdown-фенсы, лишний текст до/после, незакрытые скобки, одинарные кавычки)."
+      : reason === "empty-result"
+        ? "Твой предыдущий ответ был валидным JSON но пустым (нет нужных полей или массивы пустые)."
+        : "Твой предыдущий ответ был валидным JSON, но не соответствовал ожидаемой схеме (не все поля заполнены или неверные типы).";
+  const lines = [
+    original,
+    "",
+    "## КРИТИЧНО — это попытка номер " + attempt,
+    reasonLine,
+    "",
+    "Вот что ты вернул в прошлый раз (фрагмент):",
+    "```",
+    snippet(lastText, 600),
+    "```",
+    "",
+    "Теперь:",
+    "  1. ОДНОЙ строкой комментария `// причина: ...` опиши что было не так (для самопроверки).",
+    "  2. Сразу после комментария — корректный JSON.",
+    shape
+      ? `\nОжидаемая форма:\n${shape}`
+      : "",
+    "\nВНИМАНИЕ: ответ должен начинаться или с `//` (комментарий) или с `{`. Никаких ```fence```, никакой прозы перед JSON.",
+  ];
+  return lines.filter(Boolean).join("\n");
+}

package/packages/utilities/learn-anything/actions/_store.ts

@@ -0,0 +1,248 @@
+import { reflex } from "@host/api";
+
+/**
+ * Shared course state store. Lives in the utility's `data/` sandbox
+ * (one JSON file per course at `courses/<courseId>.json`) — bypasses
+ * the frontmatter round-tripping problem (long JSON strings → multi-line
+ * YAML → our naive client-side parser drops them). The companion KB
+ * entry of `kind:"course"` stays for human visibility / provenance
+ * badges, but it's NOT the source of truth.
+ *
+ * The body markdown rendered into the KB entry is regenerated from the
+ * full state on every write — so editing in a KB viewer would be
+ * overwritten next save (matches "agent-managed" data model).
+ */
+
+export interface CourseState {
+  courseId: string;
+  topic: string;
+  modules: Array<{
+    id: string;
+    title: string;
+    objective: string;
+    estMinutes: number;
+  }>;
+  progress: Record<string, { completed?: boolean; quizScore?: number }>;
+  wizardAnswers: Array<{ question: string; answer: string }>;
+  createdAt: string;
+  /** Bumped on every write to drive list-view re-renders. */
+  updatedAt: string;
+}
+
+const DIR = "courses";
+
+export async function writeCourse(state: CourseState): Promise<void> {
+  const path = `${DIR}/${state.courseId}.json`;
+  await reflex.fs.write({
+    path,
+    content: JSON.stringify(state, null, 2),
+  });
+}
+
+export async function readCourse(courseId: string): Promise<CourseState | null> {
+  try {
+    const { content } = await reflex.fs.read({
+      path: `${DIR}/${courseId}.json`,
+    });
+    return JSON.parse(content) as CourseState;
+  } catch {
+    return null;
+  }
+}
+
+export async function listCourses(): Promise<CourseState[]> {
+  const out: CourseState[] = [];
+  try {
+    const { entries } = await reflex.fs.list({ path: DIR });
+    for (const e of entries) {
+      if (e.isDir) continue;
+      if (!e.name.endsWith(".json")) continue;
+      const id = e.name.slice(0, -5);
+      const c = await readCourse(id);
+      if (c) out.push(c);
+    }
+  } catch {
+    /* dir not created yet → empty list */
+  }
+  // Migration fallback: pre-0.2 versions stored course state in KB
+  // frontmatter (which broke on long multi-line YAML). Pick up anything
+  // KB has that fs doesn't, hydrate from there, and persist to fs so
+  // the next open is fast and complete.
+  try {
+    const seen = new Set(out.map((c) => c.courseId));
+    const kb = (await reflex.kb.list({ kind: "course" })) ?? [];
+    for (const k of kb) {
+      try {
+        const { content } = await reflex.kb.read({ relPath: k.relPath });
+        const fm = parseFrontmatter(content);
+        const courseId = stringField(fm, "courseId") || baseSlug(k.relPath);
+        if (!courseId || seen.has(courseId)) continue;
+        const topic =
+          stringField(fm, "topic") || k.title || courseId;
+        const modulesFm = fm?.modules;
+        // Best-effort: parse JSON-string frontmatter OR rebuild a stub
+        // outline from the body's "1. **Title** — objective" lines.
+        const modules =
+          parseModulesField(modulesFm) ?? parseModulesFromBody(content);
+        if (modules.length === 0) continue;
+        const progress =
+          parseProgressField(fm?.progress) ?? {};
+        const wizardAnswers =
+          parseWizardField(fm?.wizardAnswers) ?? [];
+        const createdAt =
+          stringField(fm, "createdAt") || k.modifiedAt || new Date().toISOString();
+        const migrated: CourseState = {
+          courseId,
+          topic,
+          modules,
+          progress,
+          wizardAnswers,
+          createdAt,
+          updatedAt: new Date().toISOString(),
+        };
+        out.push(migrated);
+        seen.add(courseId);
+        // Persist so we don't pay the KB scan next time.
+        await writeCourse(migrated);
+      } catch {
+        /* skip malformed entry */
+      }
+    }
+  } catch {
+    /* kb.list unavailable — fine, just no migration */
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// KB migration helpers — only used by the fallback above.
+
+function parseFrontmatter(raw: string): Record<string, unknown> | null {
+  const m = /^---\n([\s\S]*?)\n---/.exec(raw);
+  if (!m) return null;
+  const out: Record<string, unknown> = {};
+  // Crude but tolerant: collect multi-line values when indented or
+  // explicitly quoted with single quotes. Sufficient for old courses
+  // that wrapped a long JSON string under a single key.
+  const lines = m[1]!.split("\n");
+  let curKey: string | null = null;
+  let curBuf = "";
+  const flush = () => {
+    if (curKey == null) return;
+    let v = curBuf.trim();
+    // Strip outer quotes if present.
+    v = v.replace(/^['"]|['"]$/g, "");
+    out[curKey] = v;
+    curKey = null;
+    curBuf = "";
+  };
+  for (const line of lines) {
+    if (/^\S/.test(line) && line.includes(":")) {
+      flush();
+      const i = line.indexOf(":");
+      curKey = line.slice(0, i).trim();
+      curBuf = line.slice(i + 1);
+    } else if (curKey != null) {
+      curBuf += "\n" + line;
+    }
+  }
+  flush();
+  return out;
+}
+
+function stringField(fm: Record<string, unknown> | null, key: string): string {
+  return fm && typeof fm[key] === "string" ? (fm[key] as string) : "";
+}
+
+function parseModulesField(v: unknown): CourseState["modules"] | null {
+  if (typeof v !== "string") return null;
+  try {
+    const parsed = JSON.parse(v);
+    if (!Array.isArray(parsed)) return null;
+    return parsed
+      .filter(
+        (x): x is { id: string; title: string; objective?: string } =>
+          x &&
+          typeof x === "object" &&
+          typeof (x as { id?: unknown }).id === "string",
+      )
+      .map((x) => ({
+        id: x.id,
+        title:
+          typeof (x as { title?: unknown }).title === "string"
+            ? (x as { title: string }).title
+            : x.id,
+        objective:
+          typeof (x as { objective?: unknown }).objective === "string"
+            ? (x as { objective: string }).objective
+            : "",
+        estMinutes:
+          typeof (x as { estMinutes?: unknown }).estMinutes === "number"
+            ? (x as { estMinutes: number }).estMinutes
+            : 30,
+      }));
+  } catch {
+    return null;
+  }
+}
+
+function parseProgressField(v: unknown): CourseState["progress"] | null {
+  if (typeof v !== "string") return null;
+  try {
+    const p = JSON.parse(v);
+    return p && typeof p === "object" ? (p as CourseState["progress"]) : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseWizardField(v: unknown): CourseState["wizardAnswers"] | null {
+  if (typeof v !== "string") return null;
+  try {
+    const p = JSON.parse(v);
+    return Array.isArray(p) ? (p as CourseState["wizardAnswers"]) : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseModulesFromBody(raw: string): CourseState["modules"] {
+  // Body shape from old generateOutline: "1. **Title** — objective (~N мин)"
+  const out: CourseState["modules"] = [];
+  const re = /^\s*(\d+)\.\s+\*\*(.+?)\*\*\s*[—-]\s*(.*?)(?:\s*\(~?(\d+)\s*мин\))?$/gm;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(raw))) {
+    out.push({
+      id: slug(m[2]!) || `m${m[1]}`,
+      title: m[2]!,
+      objective: m[3] ?? "",
+      estMinutes: m[4] ? Number(m[4]) : 30,
+    });
+  }
+  return out;
+}
+
+function slug(s: string): string {
+  return s
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+function baseSlug(rel: string): string {
+  return (rel.split("/").pop() ?? rel)
+    .replace(/\.md$/, "")
+    .replace(/^\d{4}-\d{2}-\d{2}-/, "");
+}
+
+export async function deleteCourse(courseId: string): Promise<void> {
+  // fs.delete isn't exposed yet; overwrite with empty marker for now.
+  // Listing skips entries that fail to parse so this effectively hides
+  // the course until a proper delete RPC ships.
+  await reflex.fs.write({
+    path: `${DIR}/${courseId}.json`,
+    content: "// deleted",
+  });
+}