chore: import upstream snapshot with attribution

2026-07-13 13:32:57 +08:00
commit cd420f9332
4811 changed files with 884702 additions and 0 deletions
@@ -0,0 +1,133 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+// Snapshots the user-facing docs into the SDK package, so AI coding agents can read the
+// version-pinned reference directly from node_modules (zero drift). Run as part of
+// `@trigger.dev/sdk`'s build, from the package dir.
+//
+// The manifest is the entire "Documentation" dropdown in `docs/docs.json` (the
+// "Resources for Trigger.dev" tab) — every page under it is bundled. Add a page to that
+// nav and it ships automatically; nothing else to edit. The API reference and
+// Guides & examples dropdowns are intentionally not bundled. Skills reference into this
+// set by path; their `sources:` frontmatter is informational and no longer drives bundling.
+//
+// Layout: nav page `tasks/overview` is copied from `docs/tasks/overview.mdx` to
+// `<sdk>/docs/tasks/overview.mdx`, so a skill at `<sdk>/skills/<name>/SKILL.md` reaches it
+// at `../../docs/tasks/overview.mdx` and an agent reaches it at `@trigger.dev/sdk/docs/...`.
+
+const packageDir = process.cwd(); // packages/trigger-sdk when run from the SDK build
+const repoRoot = path.resolve(packageDir, "..", "..");
+const docsRoot = path.join(repoRoot, "docs");
+const outDir = path.join(packageDir, "docs");
+
+const DROPDOWN = "Documentation";
+
+/** Recursively collect every page path under a docs.json nav node (groups -> pages, nested). */
+function collectPages(node: unknown): string[] {
+  const out: string[] = [];
+  if (node && typeof node === "object") {
+    const n = node as { groups?: unknown[]; pages?: unknown[] };
+    for (const g of n.groups ?? []) out.push(...collectPages(g));
+    for (const p of n.pages ?? []) {
+      if (typeof p === "string") out.push(p);
+      else out.push(...collectPages(p));
+    }
+  }
+  return out;
+}
+
+async function collectManifest(): Promise<string[]> {
+  const docsJson = JSON.parse(await fs.readFile(path.join(docsRoot, "docs.json"), "utf8"));
+  const dropdowns: Array<{ dropdown?: string }> = docsJson?.navigation?.dropdowns ?? [];
+  const documentation = dropdowns.find((d) => d.dropdown === DROPDOWN);
+
+  if (!documentation) {
+    throw new Error(`[bundleSdkDocs] "${DROPDOWN}" dropdown not found in docs/docs.json`);
+  }
+
+  // Page paths are root-relative without extension (e.g. "tasks/overview"); map to docs/*.mdx.
+  return [...new Set(collectPages(documentation))];
+}
+
+async function bundleSdkDocs() {
+  // When the SDK is built as a dependency inside a pruned workspace (e.g. the webapp Docker
+  // image), the repo-level docs/ tree is a separate workspace package that isn't part of that
+  // build's dependency graph, so it isn't present. The SDK isn't being published there, so
+  // there's nothing to bundle: skip rather than fail. Publishing always runs from the full
+  // monorepo where docs/ exists, so the guards below still protect releases.
+  try {
+    await fs.access(docsRoot);
+  } catch {
+    console.log(`[bundleSdkDocs] docs/ not present at ${docsRoot}; skipping (pruned build)`);
+    return;
+  }
+
+  const manifest = await collectManifest();
+
+  if (manifest.length === 0) {
+    // The nav structure changed shape; refuse to ship the SDK with no docs.
+    throw new Error(`[bundleSdkDocs] no pages found under the "${DROPDOWN}" dropdown`);
+  }
+
+  // Rebuild from scratch so removed pages don't linger in the package.
+  await fs.rm(outDir, { recursive: true, force: true });
+
+  const missing: string[] = [];
+  let copied = 0;
+
+  for (const rel of manifest) {
+    // Defensive: nav paths come from our own docs.json and are URL-style, but a
+    // fat-fingered `../`, a backslash, or an absolute path shouldn't be able to copy a
+    // file from outside docs/ into the package. Reject backslashes (Windows separator)
+    // and both POSIX and Windows absolute forms, then the normalized `..` traversal.
+    const safeRel = path.posix.normalize(rel);
+    if (
+      rel.includes("\\") ||
+      path.posix.isAbsolute(rel) ||
+      path.win32.isAbsolute(rel) ||
+      safeRel.startsWith("..")
+    ) {
+      throw new Error(`[bundleSdkDocs] invalid nav path "${rel}" under "${DROPDOWN}"`);
+    }
+
+    const src = path.join(docsRoot, `${safeRel}.mdx`);
+    try {
+      await fs.access(src);
+    } catch {
+      // A nav entry pointing at a nonexistent page is a docs-nav issue, not a bundler one.
+      // Warn and skip rather than fail the SDK build.
+      missing.push(rel);
+      continue;
+    }
+    const dest = path.join(outDir, `${safeRel}.mdx`);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.copyFile(src, dest);
+    copied++;
+  }
+
+  if (missing.length > 0) {
+    console.warn(
+      `[bundleSdkDocs] ${missing.length} "${DROPDOWN}" nav page(s) have no .mdx and were skipped:\n` +
+        missing.map((m) => `  - ${m}`).join("\n")
+    );
+  }
+
+  if (copied === 0) {
+    // Every nav page was missing on disk; refuse to ship the SDK with an empty docs bundle.
+    throw new Error(
+      `[bundleSdkDocs] 0 docs copied from the "${DROPDOWN}" nav; refusing empty docs bundle`
+    );
+  }
+
+  console.log(
+    `[bundleSdkDocs] bundled ${copied} docs from the "${DROPDOWN}" nav into ${path.relative(
+      repoRoot,
+      outDir
+    )}`
+  );
+}
+
+bundleSdkDocs().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});