@cursor/july 0.1.1

package/src/internal/distribution.ts

@@ -0,0 +1,97 @@
+/**
+ * Distribution facts for the running copy of the framework.
+ *
+ * The package publishes to npm as `@cursor/july` (the pre-launch codename
+ * for agentkit; bins: `agentkit` and the legacy `agent-serve` alias) but
+ * the monorepo keeps its historical `@anysphere/agent-serve` import name
+ * working via tsconfig paths (source runs) and the runtime alias hooks
+ * (compiled runs). Everything that needs to print a package name, print a
+ * CLI command, or locate the package root goes through this module.
+ */
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Published npm package name (pre-launch codename for agentkit). */
+export const PACKAGE_NAME = "@cursor/july";
+
+/** Historical monorepo package name; never published, aliased at runtime. */
+export const LEGACY_PACKAGE_NAME = "@anysphere/agent-serve";
+
+/**
+ * Future public package name; aliased with the same fallback-only semantics
+ * as PACKAGE_NAME so the eventual rename keeps authored imports working.
+ */
+export const AGENTKIT_PACKAGE_NAME = "@cursor/agentkit";
+
+/**
+ * Command name this CLI was invoked as. Both bins point at the same entry;
+ * keep help text and hints copy-pasteable for whichever the user typed.
+ */
+export const CLI_COMMAND_NAME: string = detectCliCommandName();
+
+function detectCliCommandName(): string {
+  // Only an extensionless `agent-serve` entry (the npm .bin symlink) proves
+  // the user typed the legacy alias. Shims that re-exec the real dist script
+  // (pnpm/Windows) hand us `agent-serve.js` for both bins, so anything else
+  // brands as the primary name.
+  const entry = process.argv[1];
+  if (entry !== undefined && basename(entry) === "agent-serve") {
+    return "agent-serve";
+  }
+  return "agentkit";
+}
+
+/**
+ * True when this module runs from compiled `dist/` output (a published
+ * install, or `node dist/bin/agent-serve.js`). False when running from
+ * TypeScript source under a host loader (`tsx src/bin/agent-serve.ts`),
+ * where tsconfig paths already resolve the framework's import names.
+ */
+export function isCompiledDistribution(): boolean {
+  const url = import.meta.url;
+  return !(url.endsWith(".ts") || url.endsWith(".mts"));
+}
+
+/**
+ * Package root of the running copy: `src|dist/internal/distribution.*` is
+ * always two directories below it.
+ */
+export function packageRootDir(): string {
+  return fileURLToPath(new URL("../..", import.meta.url));
+}
+
+/** Version of the running package (from its own package.json). */
+export function packageVersion(): string {
+  const raw = readFileSync(
+    new URL("../../package.json", import.meta.url),
+    "utf8"
+  );
+  const parsed = JSON.parse(raw) as { version?: unknown };
+  return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+}
+
+/**
+ * Authoring entry subpaths and their dist-relative output files — the
+ * runtime mirror of the package `exports` map (the source of truth;
+ * `authored-loaders.test.ts` asserts they stay identical). The alias hooks
+ * derive `@anysphere/agent-serve[/x]`, `@cursor/july[/x]`, and
+ * `@cursor/agentkit[/x]` targets from this list.
+ */
+export const AUTHORING_ENTRY_FILES: ReadonlyArray<
+  readonly [subpath: string, file: string]
+> = [
+  ["", "index.js"],
+  ["tools", "tools.js"],
+  ["channels", "channels.js"],
+  ["channels/slack", "channels/slack/index.js"],
+  ["channels/github", "channels/github/index.js"],
+  ["skills", "skills.js"],
+  ["schedules", "schedules.js"],
+  ["reminders", "reminders.js"],
+  ["connections", "connections.js"],
+  ["hooks", "hooks.js"],
+  ["evals", "evals.js"],
+  ["ab", "ab.js"],
+];

package/src/internal/docs-site.ts

@@ -0,0 +1,191 @@
+/**
+ * Serves the built VitePress documentation site at `/docs`.
+ *
+ * The site is built from the package's `docs/` markdown into `dist/docs/`
+ * (`pnpm run docs:build`; VitePress `base` is `/docs/`, so asset URLs
+ * resolve under the mount). `serve` auto-builds it when the local
+ * vitepress toolchain is present (source checkouts); published installs
+ * ship the prebuilt site inside `dist/**`.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, extname, join, normalize, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { STATIC_CONTENT_TYPES } from "./playground/static.js";
+
+// src|dist/internal/docs-site.ts → packages/agent-serve/dist/docs/.
+const DOCS_DIST_DIR = fileURLToPath(
+  new URL("../../dist/docs/", import.meta.url)
+);
+const DOCS_INDEX_HTML = join(DOCS_DIST_DIR, "index.html");
+
+/** Whether `pnpm run docs:build` has produced the docs site. */
+export function docsSiteExists(): boolean {
+  return existsSync(DOCS_INDEX_HTML);
+}
+
+/**
+ * Resolve a request path under the docs mount to a file inside the built
+ * site, or undefined when it escapes the site or does not exist. VitePress
+ * emits one `.html` per page, so clean URLs resolve through the chain:
+ * exact file → directory `index.html` → `<path>.html`.
+ */
+export function resolveDocsFile(
+  requestPath: string,
+  distDir: string = DOCS_DIST_DIR
+): string | undefined {
+  const decoded = requestPath
+    .split("/")
+    .filter((part) => part !== "")
+    .join("/");
+  const normalized = normalize(decoded === "" ? "." : decoded);
+  if (normalized.startsWith("..") || normalized.includes(`..${sep}`)) {
+    return undefined;
+  }
+  const root = distDir.endsWith(sep) ? distDir : `${distDir}${sep}`;
+  const base = join(root, normalized);
+  if (base !== root.slice(0, -1) && !base.startsWith(root)) {
+    return undefined;
+  }
+  for (const candidate of [base, join(base, "index.html"), `${base}.html`]) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+/** Serve one path from the built docs site. */
+export function renderDocsFile(requestPath: string): Response {
+  if (!docsSiteExists()) {
+    return new Response(fallbackHtml(), {
+      status: 503,
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+  }
+  const filePath = resolveDocsFile(requestPath);
+  if (filePath === undefined) {
+    const notFound = join(DOCS_DIST_DIR, "404.html");
+    return new Response(
+      existsSync(notFound) ? readFileSync(notFound, "utf8") : "Not found",
+      {
+        status: 404,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      }
+    );
+  }
+  const body = readFileSync(filePath);
+  const type =
+    STATIC_CONTENT_TYPES[extname(filePath).toLowerCase()] ??
+    "application/octet-stream";
+  const hashed = filePath.includes(`${sep}assets${sep}`);
+  return new Response(new Uint8Array(body), {
+    headers: {
+      "content-type": type,
+      // VitePress content-hashes everything under assets/; pages are not
+      // hashed and must revalidate so rebuilt docs show up.
+      "cache-control": hashed
+        ? "public, max-age=31536000, immutable"
+        : "no-cache",
+    },
+  });
+}
+
+/**
+ * If the docs site is missing and the local vitepress toolchain is
+ * available, build it. No-op when the site already exists. Soft-skips
+ * (logs) when vitepress is absent so published installs without a
+ * prebuilt site still start.
+ */
+export async function ensureDocsSiteBundle(
+  logger: (line: string) => void = console.log
+): Promise<void> {
+  if (docsSiteExists()) {
+    return;
+  }
+  const toolchain = resolveDocsToolchain();
+  if (toolchain === undefined) {
+    logger(
+      "[agent-serve] docs site missing and vitepress toolchain unavailable; /docs will show a build hint"
+    );
+    return;
+  }
+  logger("[agent-serve] building docs site (vitepress)...");
+  const code = await new Promise<number>((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      [toolchain.vitepressCli, "build", "docs"],
+      { cwd: toolchain.packageRoot, env: process.env, stdio: "inherit" }
+    );
+    child.on("error", reject);
+    child.on("exit", (exitCode) => resolve(exitCode ?? 1));
+  });
+  if (code !== 0) {
+    throw new Error(`docs vitepress build failed (exit ${code})`);
+  }
+  if (!docsSiteExists()) {
+    throw new Error(
+      "docs vitepress build finished but dist/docs/index.html is missing"
+    );
+  }
+  logger("[agent-serve] docs site build complete");
+}
+
+interface DocsToolchain {
+  packageRoot: string;
+  vitepressCli: string;
+}
+
+/** True when docs sources + a resolvable `vitepress` CLI are present. */
+function resolveDocsToolchain(): DocsToolchain | undefined {
+  const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
+  if (!existsSync(join(packageRoot, "docs", ".vitepress", "config.mts"))) {
+    return undefined;
+  }
+  try {
+    const require = createRequire(join(packageRoot, "package.json"));
+    const pkgPath = require.resolve("vitepress/package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
+      bin?: string | Record<string, string>;
+    };
+    const binRel =
+      typeof pkg.bin === "string"
+        ? pkg.bin
+        : (pkg.bin?.vitepress ?? "bin/vitepress.js");
+    const vitepressCli = join(dirname(pkgPath), binRel);
+    return existsSync(vitepressCli) ? { packageRoot, vitepressCli } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function fallbackHtml(): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>agent-serve docs</title>
+    <style>
+      body { margin: 0; background: #0e1116; color: #e6edf3; font: 14px/1.6 ui-sans-serif, system-ui, sans-serif; }
+      .box { max-width: 640px; margin: 64px auto; padding: 0 24px; }
+      code { background: #1b212b; padding: 2px 6px; border-radius: 6px; font-family: ui-monospace, monospace; }
+      h1 { font-size: 18px; }
+    </style>
+  </head>
+  <body>
+    <div class="box">
+      <h1>Docs site not built</h1>
+      <p>
+        The documentation site has not been built yet. <code>agent-serve serve</code>
+        auto-builds it when the vitepress toolchain is available; otherwise run
+        <code>pnpm run docs:build</code> from <code>packages/agent-serve</code>.
+        The markdown sources are always readable under <code>docs/</code>.
+      </p>
+    </div>
+  </body>
+</html>`;
+}

package/src/internal/duration.ts

@@ -0,0 +1,39 @@
+/**
+ * Relative duration strings for reminder schedules (`every` / `delay`).
+ * Thin wrapper around the `ms` package (`30s`, `5m`, `2h`, `1d`, …).
+ */
+
+import ms from "ms";
+
+/** Parse a relative duration into milliseconds. Throws on invalid input. */
+export function parseDuration(input: string | number): number {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input) || input < 0) {
+      throw new Error(`Invalid duration ms: ${input}`);
+    }
+    return Math.floor(input);
+  }
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw new Error("Invalid duration: empty string");
+  }
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed);
+  }
+  const parsed = ms(trimmed as ms.StringValue);
+  if (typeof parsed !== "number" || !Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(
+      `Invalid duration "${input}": expected e.g. "30s", "5m", "2h", "1d"`
+    );
+  }
+  return Math.floor(parsed);
+}
+
+export function isValidDuration(input: string | number): boolean {
+  try {
+    parseDuration(input);
+    return true;
+  } catch {
+    return false;
+  }
+}