npm - @learnpack/learnpack - Versions diffs - 5.0.355 → 5.0.357 - Mend

@learnpack/learnpack 5.0.355 → 5.0.357

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (120) hide show

package/lib/commands/serve.d.ts +0 -17
package/lib/commands/serve.js +159 -129
package/lib/creatorDist/assets/{index-DnthLsvb.js → index-D6pmbMe9.js} +14030 -13903
package/lib/creatorDist/assets/index-zrPponAn.css +1701 -0
package/lib/creatorDist/index.html +2 -2
package/lib/models/creator.d.ts +1 -1
package/lib/services/ingest/adapters/gcsCourseStorage.d.ts +13 -0
package/lib/services/ingest/adapters/gcsCourseStorage.js +58 -0
package/lib/services/ingest/adapters/rigoUserTokenAuth.d.ts +15 -0
package/lib/services/ingest/adapters/rigoUserTokenAuth.js +46 -0
package/lib/services/ingest/adapters/rigobotPackageRegistry.d.ts +7 -0
package/lib/services/ingest/adapters/rigobotPackageRegistry.js +119 -0
package/lib/services/ingest/core/buildIngestConfig.d.ts +27 -0
package/lib/services/ingest/core/buildIngestConfig.js +40 -0
package/lib/services/ingest/core/buildInitialSyllabus.d.ts +24 -0
package/lib/services/ingest/core/buildInitialSyllabus.js +104 -0
package/lib/services/ingest/core/buildSidebar.d.ts +13 -0
package/lib/services/ingest/core/buildSidebar.js +28 -0
package/lib/services/ingest/core/coursePaths.d.ts +31 -0
package/lib/services/ingest/core/coursePaths.js +50 -0
package/lib/services/ingest/core/ingestCoursePackage.d.ts +52 -0
package/lib/services/ingest/core/ingestCoursePackage.js +217 -0
package/lib/services/ingest/core/normalizeLearnJson.d.ts +25 -0
package/lib/services/ingest/core/normalizeLearnJson.js +29 -0
package/lib/services/ingest/core/pairLessons.d.ts +29 -0
package/lib/services/ingest/core/pairLessons.js +102 -0
package/lib/services/ingest/core/planWrites.d.ts +44 -0
package/lib/services/ingest/core/planWrites.js +59 -0
package/lib/services/ingest/core/resolveSlug.d.ts +53 -0
package/lib/services/ingest/core/resolveSlug.js +93 -0
package/lib/services/ingest/core/types.d.ts +53 -0
package/lib/services/ingest/core/types.js +2 -0
package/lib/services/ingest/core/validatePackage.d.ts +38 -0
package/lib/services/ingest/core/validatePackage.js +97 -0
package/lib/services/ingest/createIngestService.d.ts +34 -0
package/lib/services/ingest/createIngestService.js +38 -0
package/lib/services/ingest/errors.d.ts +22 -0
package/lib/services/ingest/errors.js +34 -0
package/lib/services/ingest/http/errorMapping.d.ts +8 -0
package/lib/services/ingest/http/errorMapping.js +40 -0
package/lib/services/ingest/http/router.d.ts +32 -0
package/lib/services/ingest/http/router.js +124 -0
package/lib/services/ingest/http/zipPackageReader.d.ts +26 -0
package/lib/services/ingest/http/zipPackageReader.js +62 -0
package/lib/services/ingest/ports/courseStorage.d.ts +25 -0
package/lib/services/ingest/ports/courseStorage.js +2 -0
package/lib/services/ingest/ports/packageRegistry.d.ts +58 -0
package/lib/services/ingest/ports/packageRegistry.js +2 -0
package/lib/services/ingest/ports/requestAuthenticator.d.ts +25 -0
package/lib/services/ingest/ports/requestAuthenticator.js +2 -0
package/lib/utils/coursePackage/bucketIo.d.ts +23 -0
package/lib/utils/coursePackage/bucketIo.js +36 -0
package/lib/utils/coursePackage/learnJson.d.ts +26 -0
package/lib/utils/coursePackage/learnJson.js +36 -0
package/lib/utils/coursePackage/sidebar.d.ts +15 -0
package/lib/utils/coursePackage/sidebar.js +26 -0
package/lib/utils/creatorSocket.js +15 -21
package/lib/utils/gcpCredentials.d.ts +18 -0
package/lib/utils/gcpCredentials.js +27 -0
package/lib/utils/rigoActions.d.ts +16 -0
package/lib/utils/rigoActions.js +102 -1
package/lib/utils/socketRegistry.d.ts +46 -0
package/lib/utils/socketRegistry.js +83 -0
package/package.json +1 -1
package/src/commands/serve.ts +162 -114
package/src/creator/README.md +63 -51
package/src/creator/package-lock.json +1188 -8
package/src/creator/package.json +5 -1
package/src/creator/src/App.tsx +120 -54
package/src/creator/src/components/FileUploader.tsx +1 -12
package/src/creator/src/components/NotificationListener.tsx +1 -8
package/src/creator/src/components/syllabus/SyllabusEditor.tsx +101 -36
package/src/creator/src/locales/en.json +8 -0
package/src/creator/src/locales/es.json +8 -0
package/src/creator/src/utils/completionResult.test.ts +144 -0
package/src/creator/src/utils/completionResult.ts +154 -0
package/src/creator/src/utils/constants.ts +17 -4
package/src/creator/src/utils/socket.test.ts +113 -0
package/src/creator/src/utils/socket.ts +60 -37
package/src/creator/src/utils/store.ts +84 -67
package/src/creator/src/utils/useCompletionWatchdog.test.ts +99 -0
package/src/creator/src/utils/useCompletionWatchdog.ts +37 -0
package/src/creator/vitest.config.ts +16 -0
package/src/creatorDist/assets/{index-DnthLsvb.js → index-D6pmbMe9.js} +14030 -13903
package/src/creatorDist/assets/index-zrPponAn.css +1701 -0
package/src/creatorDist/index.html +2 -2
package/src/models/creator.ts +1 -1
package/src/services/ingest/adapters/gcsCourseStorage.ts +70 -0
package/src/services/ingest/adapters/rigoUserTokenAuth.ts +65 -0
package/src/services/ingest/adapters/rigobotPackageRegistry.ts +161 -0
package/src/services/ingest/core/buildIngestConfig.ts +51 -0
package/src/services/ingest/core/buildInitialSyllabus.ts +122 -0
package/src/services/ingest/core/buildSidebar.ts +32 -0
package/src/services/ingest/core/coursePaths.ts +59 -0
package/src/services/ingest/core/ingestCoursePackage.ts +343 -0
package/src/services/ingest/core/normalizeLearnJson.ts +47 -0
package/src/services/ingest/core/pairLessons.ts +132 -0
package/src/services/ingest/core/planWrites.ts +91 -0
package/src/services/ingest/core/resolveSlug.ts +119 -0
package/src/services/ingest/core/types.ts +57 -0
package/src/services/ingest/core/validatePackage.ts +132 -0
package/src/services/ingest/createIngestService.ts +66 -0
package/src/services/ingest/errors.ts +45 -0
package/src/services/ingest/http/errorMapping.ts +49 -0
package/src/services/ingest/http/router.ts +156 -0
package/src/services/ingest/http/zipPackageReader.ts +81 -0
package/src/services/ingest/ports/courseStorage.ts +25 -0
package/src/services/ingest/ports/packageRegistry.ts +60 -0
package/src/services/ingest/ports/requestAuthenticator.ts +28 -0
package/src/ui/_app/app.js +325 -325
package/src/ui/app.tar.gz +0 -0
package/src/utils/coursePackage/bucketIo.ts +46 -0
package/src/utils/coursePackage/learnJson.ts +37 -0
package/src/utils/coursePackage/sidebar.ts +28 -0
package/src/utils/creatorSocket.ts +16 -22
package/src/utils/gcpCredentials.ts +38 -0
package/src/utils/rigoActions.ts +163 -0
package/src/utils/socketRegistry.ts +85 -0
package/lib/creatorDist/assets/index-CjddKHB_.css +0 -1
package/src/creatorDist/assets/index-CjddKHB_.css +0 -1

package/src/creatorDist/index.html CHANGED Viewed

@@ -10,8 +10,8 @@
     />
     <title>Learnpack Creator: Craft tutorials in seconds!</title>
-    <script type="module" crossorigin src="/creator/assets/index-DnthLsvb.js"></script>
-    <link rel="stylesheet" crossorigin href="/creator/assets/index-CjddKHB_.css">
+    <script type="module" crossorigin src="/creator/assets/index-D6pmbMe9.js"></script>
+    <link rel="stylesheet" crossorigin href="/creator/assets/index-zrPponAn.css">
   </head>
   <body>
     <div id="root"></div>

package/src/models/creator.ts CHANGED Viewed

@@ -3,7 +3,7 @@ export interface SyncNotification {
   sourceLanguage: string; // Language code from which sync will occur
   createdAt: number; // Creation timestamp
   updatedAt: number; // Last update timestamp
-  status: "pending" | "processing" | "completed" | "error";
+  status: "pending" | "processing" | "completed" | "partial" | "error";
   processingLastUpdate?: number; // Last update timestamp during processing
   error?: {
     message: string;

package/src/services/ingest/adapters/gcsCourseStorage.ts ADDED Viewed

@@ -0,0 +1,70 @@
+import { Bucket } from "@google-cloud/storage"
+import { CourseStorage } from "../ports/courseStorage"
+import { IngestError } from "../errors"
+import { uploadFileToBucket } from "../../../utils/coursePackage/bucketIo"
+/**
+ * GCS-backed course storage.
+ *
+ * Writes go through `uploadFileToBucket` rather than `bucket.file().save()`
+ * directly: that helper sanitizes README newlines, and a second write path to
+ * the same bucket that skipped it would store content the translation step
+ * later chokes on.
+ * @param bucket - Bucket holding course drafts.
+ * @returns A CourseStorage backed by that bucket.
+ */
+export function createGcsCourseStorage(bucket: Bucket): CourseStorage {
+  return {
+    async write(path, content) {
+      try {
+        await uploadFileToBucket(bucket, content, path)
+      } catch (error) {
+        throw new IngestError(
+          "STORAGE_FAILURE",
+          `Could not write ${path}`,
+          error
+        )
+      }
+    },
+    async read(path) {
+      try {
+        const [buf] = await bucket.file(path).download()
+        return buf.toString()
+      } catch {
+        // A missing object and an unreadable one are indistinguishable here
+        // without inspecting the GCS error code; callers treat both as absent.
+        return null
+      }
+    },
+    async list(prefix) {
+      try {
+        const [files] = await bucket.getFiles({ prefix })
+        return files.map(file => file.name)
+      } catch (error) {
+        throw new IngestError(
+          "STORAGE_FAILURE",
+          `Could not list objects under ${prefix}`,
+          error
+        )
+      }
+    },
+    async deleteMany(paths) {
+      if (paths.length === 0) {
+        return
+      }
+      try {
+        await Promise.all(paths.map(path => bucket.file(path).delete()))
+      } catch (error) {
+        throw new IngestError(
+          "STORAGE_FAILURE",
+          `Could not delete ${paths.length} object(s)`,
+          error
+        )
+      }
+    },
+  }
+}

package/src/services/ingest/adapters/rigoUserTokenAuth.ts ADDED Viewed

@@ -0,0 +1,65 @@
+import axios from "axios"
+import { RIGOBOT_HOST } from "../../../utils/api"
+import { Identity, RequestAuthenticator } from "../ports/requestAuthenticator"
+import { IngestError } from "../errors"
+const TOKEN_HEADER = "x-rigo-token"
+const readHeader = (
+  headers: Record<string, string | string[] | undefined>,
+  name: string
+): string => {
+  const raw = headers[name] ?? headers[name.toLowerCase()]
+  const value = Array.isArray(raw) ? raw[0] : raw
+  return (value || "").trim()
+}
+/**
+ * Authenticates a request by its Rigobot user token.
+ *
+ * Most of `serve.ts` reads this header without checking it, which turns a stale
+ * token into an opaque failure several calls deeper. One round trip up front
+ * costs little and names the problem where it happened.
+ *
+ * Note this validates rather than reusing `isValidRigoToken` from
+ * `utils/rigoActions`: that one calls Node's global fetch even though the
+ * package declares support for Node 14, and propagating that is not worth the
+ * five lines it would save.
+ * @returns A RequestAuthenticator backed by Rigobot's token endpoint.
+ */
+export function createRigoUserTokenAuth(): RequestAuthenticator {
+  return {
+    async authenticate(headers): Promise<Identity> {
+      const rigoToken = readHeader(headers, TOKEN_HEADER)
+      if (!rigoToken) {
+        throw new IngestError(
+          "INVALID_TOKEN",
+          `Missing ${TOKEN_HEADER} header`
+        )
+      }
+      try {
+        await axios.get(
+          `${RIGOBOT_HOST}/v1/auth/token/${encodeURIComponent(rigoToken)}`
+        )
+      } catch (error) {
+        if (axios.isAxiosError(error) && error.response) {
+          throw new IngestError(
+            "INVALID_TOKEN",
+            "Rigobot rejected the token",
+            error
+          )
+        }
+        throw new IngestError(
+          "REGISTRY_UNAVAILABLE",
+          "Could not reach Rigobot to validate the token",
+          error
+        )
+      }
+      return { rigoToken }
+    },
+  }
+}

package/src/services/ingest/adapters/rigobotPackageRegistry.ts ADDED Viewed

@@ -0,0 +1,161 @@
+import axios from "axios"
+import api, { RIGOBOT_HOST } from "../../../utils/api"
+import {
+  PackageRegistry,
+  RigoOrganization,
+  RigoPackage,
+} from "../ports/packageRegistry"
+import { IngestError } from "../errors"
+/** Rigobot rejects a duplicate slug with a 400 whose body names the conflict. */
+const SLUG_CONFLICT_PATTERN = /already (taken|in use)/i
+const authHeaders = (rigoToken: string) => ({
+  // Tokens read from a .env file routinely carry a trailing newline, which
+  // makes the header invalid in a way the server reports as a plain 401.
+  Authorization: `Token ${rigoToken.replace(/[\n\r]/g, "").trim()}`,
+})
+const toRigoPackage = (data: any): RigoPackage => ({
+  id: data.id,
+  package_slug: data.package_slug,
+  organization: data.organization ?? null,
+  status: data.status,
+})
+/**
+ * Turns an axios failure into a typed ingest failure.
+ * @param error - Whatever the request rejected with.
+ * @param context - Short description of the attempted operation.
+ * @returns Never — always throws.
+ */
+function rethrowAsIngestError(error: unknown, context: string): never {
+  if (axios.isAxiosError(error)) {
+    const status = error.response?.status
+    if (status === 401 || status === 403) {
+      throw new IngestError(
+        "INVALID_TOKEN",
+        `Rigobot rejected the token while ${context}`,
+        error
+      )
+    }
+  }
+  throw new IngestError(
+    "REGISTRY_UNAVAILABLE",
+    `Rigobot request failed while ${context}`,
+    error
+  )
+}
+/**
+ * Rigobot-backed package registry.
+ * @param rigoToken - Rigobot user token owning the packages.
+ * @returns A PackageRegistry talking to RIGOBOT_HOST.
+ */
+export function createRigobotPackageRegistry(
+  rigoToken: string
+): PackageRegistry {
+  return {
+    async isSlugAvailable(slug) {
+      try {
+        const response = await axios.get<{ available?: boolean }>(
+          `${RIGOBOT_HOST}/v1/learnpack/check-slug-availability`,
+          { params: { slug } }
+        )
+        return response.data.available === true
+      } catch (error) {
+        rethrowAsIngestError(error, `checking availability of "${slug}"`)
+      }
+    },
+    async createPackage(slug, config) {
+      try {
+        const data = await api.createRigoPackage(rigoToken, slug, config)
+        return toRigoPackage(data)
+      } catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 400) {
+          const detail = String(error.response.data?.error ?? "")
+          if (SLUG_CONFLICT_PATTERN.test(detail)) {
+            throw new IngestError(
+              "SLUG_TAKEN",
+              `The slug "${slug}" is already registered`,
+              error
+            )
+          }
+        }
+        rethrowAsIngestError(error, `creating the package "${slug}"`)
+      }
+    },
+    async getPackageBySlug(slug) {
+      try {
+        const response = await axios.get(
+          `${RIGOBOT_HOST}/v1/learnpack/package/${encodeURIComponent(slug)}/`,
+          { headers: authHeaders(rigoToken) }
+        )
+        return toRigoPackage(response.data)
+      } catch (error) {
+        // Rigobot answers 404 for "no such package" and 403 for one owned by
+        // somebody else. Both mean "not yours to read"; the caller decides what
+        // that implies, so neither is an error here.
+        if (
+          axios.isAxiosError(error) &&
+          (error.response?.status === 404 || error.response?.status === 403)
+        ) {
+          return null
+        }
+        rethrowAsIngestError(error, `reading the package "${slug}"`)
+      }
+    },
+    async listOrganizations() {
+      try {
+        const response = await axios.get(
+          `${RIGOBOT_HOST}/v1/auth/me/organization`,
+          { headers: authHeaders(rigoToken) }
+        )
+        // Paginated endpoints answer with `results`; unpaginated ones with a
+        // bare array.
+        const rows = Array.isArray(response.data) ?
+          response.data :
+          response.data?.results ?? []
+        return rows.map(
+          (row: any): RigoOrganization => ({ id: row.id, name: row.name })
+        )
+      } catch (error) {
+        rethrowAsIngestError(error, "listing your organizations")
+      }
+    },
+    async assignOrganization(packageId, organizationId) {
+      try {
+        await axios.put(
+          `${RIGOBOT_HOST}/v1/learnpack/organization/package/${packageId}`,
+          { organization: organizationId },
+          { headers: authHeaders(rigoToken) }
+        )
+      } catch (error) {
+        // Rigobot only accepts this while the organization is still null, and
+        // answers 400 once one is set. There is no detach endpoint, so this is
+        // terminal rather than retryable.
+        if (axios.isAxiosError(error) && error.response?.status === 400) {
+          throw new IngestError(
+            "ORGANIZATION_MISMATCH",
+            `Package ${packageId} could not be assigned to organization ${organizationId}: ${
+              error.response.data?.error ?? "it already belongs to one"
+            }`,
+            error
+          )
+        }
+        rethrowAsIngestError(
+          error,
+          `assigning package ${packageId} to organization ${organizationId}`
+        )
+      }
+    },
+  }
+}

package/src/services/ingest/core/buildIngestConfig.ts ADDED Viewed

@@ -0,0 +1,51 @@
+import { ConfigResponse, Exercise } from "../../../utils/configBuilder"
+import { getReadmeExtension } from "../../../utils/creatorUtilities"
+import { IngestLesson } from "./types"
+export type BuildIngestConfigInput = {
+  lessons: IngestLesson[];
+  /** The package's learn.json, already normalized. */
+  learnJson: Record<string, unknown>;
+};
+/**
+ * Derives `.learn/config.json` without going back to the bucket.
+ *
+ * `buildConfig` (`utils/configBuilder.ts:47`) produces the same shape, but it
+ * reads the bucket for exactly two things — the object listing and learn.json —
+ * and the ingest already holds both in memory by the time it gets here. Writing
+ * the course and then reading it back to describe it would be a round trip that
+ * answers a question we already know.
+ *
+ * The file has to exist because `POST /actions/publish/:slug` reads it as its
+ * first step and fails outright when it is missing; without this, publishing a
+ * course nobody had opened in the creator would 500. `GET /config` regenerates
+ * it from the bucket on every call, so this version only has to carry publish
+ * through: its title, description and duration, plus each exercise's slug and
+ * translations. `exercise.files` is never read anywhere in the publish flow,
+ * which is why an empty list is honest rather than lazy.
+ * @param input - Paired lessons and the normalized learn.json.
+ * @returns The `{ config, exercises }` pair the bucket stores.
+ */
+export function buildIngestConfig(
+  input: BuildIngestConfigInput
+): ConfigResponse {
+  const exercises: Exercise[] = input.lessons.map((lesson, position) => {
+    const translations: Record<string, string> = {}
+    for (const lang of lesson.languages) {
+      translations[lang] = `README${getReadmeExtension(lang)}`
+    }
+    return {
+      title: lesson.title,
+      slug: lesson.exerciseSlug,
+      graded: false,
+      files: [],
+      translations,
+      position,
+    }
+  })
+  return { config: { ...input.learnJson }, exercises }
+}

package/src/services/ingest/core/buildInitialSyllabus.ts ADDED Viewed

@@ -0,0 +1,122 @@
+import { Lesson, Syllabus, TDifficulty } from "../../../models/creator"
+import { IngestLesson } from "./types"
+export type BuildSyllabusInput = {
+  slug: string;
+  language: string;
+  lessons: IngestLesson[];
+  /** The package's `learn.json`, already normalized. */
+  learnJson: Record<string, unknown>;
+  /** Injectable clock, so tests can assert on timestamps. */
+  now?: number;
+};
+const pickLocalized = (value: unknown, language: string): string => {
+  if (typeof value === "string") {
+    return value
+  }
+  if (!value || typeof value !== "object") {
+    return ""
+  }
+  const map = value as Record<string, string>
+  const candidate = map[language] || Object.values(map)[0]
+  return typeof candidate === "string" ? candidate : ""
+}
+/**
+ * Builds the `courseInfo` half of the syllabus.
+ *
+ * The six wizard-owned fields carry their "nothing pending" values rather than
+ * a guess: an ingested course was never authored in the creator, so there is no
+ * step to resume and no content index to honour. Same reasoning, and same
+ * values, as `buildCourseInfo` in `utils/repair/legacyPackageRepair.ts`.
+ * @param input - Course slug, language and learn.json.
+ * @returns The courseInfo object.
+ */
+function buildCourseInfo(input: BuildSyllabusInput): Syllabus["courseInfo"] {
+  const { learnJson, language, slug } = input
+  const difficulty = learnJson.difficulty
+  const duration = learnJson.duration
+  return {
+    title: pickLocalized(learnJson.title, language) || slug,
+    description: pickLocalized(learnJson.description, language),
+    duration: typeof duration === "number" ? duration : 0,
+    difficulty: (typeof difficulty === "string" ?
+      difficulty :
+      "beginner") as TDifficulty,
+    language,
+    technologies: Array.isArray(learnJson.technologies) ?
+      (learnJson.technologies as string[]) :
+      [],
+    slug,
+    hasContentIndex: false,
+    contentIndex: "",
+    isCompleted: true,
+    variables: [],
+    currentStep: "",
+    purpose: "",
+  }
+}
+/**
+ * Builds the `initialSyllabus.json` for a course whose content already exists.
+ *
+ * The sibling of `buildSyllabusFromSources`
+ * (`utils/repair/legacyPackageRepair.ts:363`), which solves the same problem
+ * for packages that predate the creator. That one has to infer titles from an
+ * H1 and types from a heuristic; here the generator's plan already knows both,
+ * so the inference is skipped and the real values are used. The invariants
+ * below are shared between the two — change one and check the other.
+ * @param input - Paired lessons plus course metadata.
+ * @returns A syllabus the creator treats as a finished course.
+ */
+export function buildInitialSyllabus(input: BuildSyllabusInput): Syllabus {
+  const now = input.now ?? Date.now()
+  const lessons: Lesson[] = input.lessons.map(lesson => {
+    const translations: NonNullable<Lesson["translations"]> = {}
+    for (const lang of lesson.languages) {
+      // Deliberately without `sourceContentHash` or `descriptionPromptVersion`:
+      // their absence is what makes `workList.needsGeneration` return true, so
+      // the descriptions backfill picks this course up on its next run.
+      //
+      // `completedAt` must be truthy — the IDE reads a `startedAt` without one
+      // as a translation still in flight and shows a spinner on a finished
+      // course. `completionId` is only ever written, never read back to query
+      // Rigobot, so zero is safe.
+      translations[lang] = {
+        completionId: 0,
+        startedAt: now,
+        completedAt: now,
+      }
+    }
+    return {
+      id: lesson.id,
+      // The exercise folder slug, not a random id: it is the lookup key the
+      // rest of the server matches on, and it travels inside webhook URLs.
+      uid: lesson.exerciseSlug,
+      title: lesson.title,
+      type: lesson.type,
+      description: lesson.description,
+      duration: lesson.durationMinutes,
+      // This pair is what tells the whole UI the course is finished: without
+      // `generated`, the publish button reports unreviewed lessons; without
+      // `status`, Rigobot's agent believes it may still generate content.
+      generated: true,
+      status: "DONE" as const,
+      // Must exist even when empty — `syllabusHash` in serve.ts calls
+      // Object.entries on it with no optional chaining, on nearly every request.
+      translations,
+    }
+  })
+  return {
+    lessons,
+    courseInfo: buildCourseInfo(input),
+  }
+}

package/src/services/ingest/core/buildSidebar.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import { TSidebar } from "../../../utils/sidebarGenerator"
+import { IngestLesson } from "./types"
+/**
+ * Builds `sidebar.json`: `{ [exerciseSlug]: { [lang]: title } }`.
+ *
+ * Unlike `createInitialSidebar` (`utils/coursePackage/sidebar.ts`), which files
+ * each entry under its own slug as a placeholder, an ingested course already
+ * has real titles — the creator flow only uses slugs because at creation time
+ * no lesson has been written yet.
+ * @param lessons - Paired lessons, in the order they should appear.
+ * @returns The sidebar, keyed by exercise folder slug.
+ */
+export function buildSidebar(lessons: IngestLesson[]): TSidebar {
+  const sidebar: TSidebar = {}
+  for (const lesson of lessons) {
+    const entry: Record<string, string> = {}
+    for (const lang of lesson.languages) {
+      entry[lang] = lesson.title
+    }
+    // A lesson with no README in any language would key an empty object, which
+    // reads to the IDE as a lesson with no titles at all.
+    if (Object.keys(entry).length > 0) {
+      sidebar[lesson.exerciseSlug] = entry
+    }
+  }
+  return sidebar
+}

package/src/services/ingest/core/coursePaths.ts ADDED Viewed

@@ -0,0 +1,59 @@
+/**
+ * Where each part of an ingested course lives in the bucket.
+ *
+ * Deliberately a copy of `gcsLayout` (`utils/repair/repairStorage.ts:93`)
+ * rather than an import: that module pulls in `@google-cloud/storage` and the
+ * AWS SDK at its top, and the ingest core must stay free of infrastructure.
+ *
+ * The two agreeing is load-bearing, though — the repair pass writes to the same
+ * bucket, so a disagreement about where a file belongs would have it "fix" a
+ * course the ingest had just written correctly. A test asserts the two match;
+ * that is what keeps this copy honest.
+ */
+export const COURSES_PREFIX = "courses"
+// Everything under one course.
+export const coursePrefix = (slug: string): string =>
+  `${COURSES_PREFIX}/${slug}/`
+export const learnJsonPath = (slug: string): string =>
+  `${COURSES_PREFIX}/${slug}/learn.json`
+export const configPath = (slug: string): string =>
+  `${COURSES_PREFIX}/${slug}/.learn/config.json`
+export const syllabusPath = (slug: string): string =>
+  `${COURSES_PREFIX}/${slug}/.learn/initialSyllabus.json`
+export const sidebarPath = (slug: string): string =>
+  `${COURSES_PREFIX}/${slug}/.learn/sidebar.json`
+export const exercisesPrefix = (slug: string): string =>
+  `${COURSES_PREFIX}/${slug}/exercises/`
+// Generation artifacts kept alongside the course. Same path the streaming
+// persistence design reserves for them, so the generator can later write here
+// directly without a migration.
+export const artifactsPrefix = (slug: string): string =>
+  `${COURSES_PREFIX}/${slug}/.learn/artifacts/`
+export const exerciseFilePath = (
+  slug: string,
+  exerciseSlug: string,
+  fileName: string
+): string => `${exercisesPrefix(slug)}${exerciseSlug}/${fileName}`
+/**
+ * The prefixes the ingest owns and may prune on overwrite.
+ *
+ * Everything else under the course belongs to somebody else: preview images the
+ * user uploaded, `package-manifest.json`, the publish journal. Deleting outside
+ * these two would destroy work the ingest never created.
+ * @param slug - Course slug.
+ * @returns Prefixes safe to prune.
+ */
+export const prunablePrefixes = (slug: string): string[] => [
+  exercisesPrefix(slug),
+  artifactsPrefix(slug),
+]