blume 2.0.1 → 2.0.3

package/src/ai/relative-links.ts

@@ -1,8 +1,15 @@
 import { basename } from "pathe";
 
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import {
+  isInternalPath,
+  mountBasePath,
+  normalizeBasePath,
+  withAuthoredBasePath,
+  withBasePath,
+} from "../core/base-path.ts";
 import { nextFenceState } from "../core/code-fences.ts";
 import type { FenceState } from "../core/code-fences.ts";
+import { localePrefix } from "../core/i18n.ts";
 import {
   buildFileRouteIndex,
   isIndexFileName,
@@ -10,19 +17,27 @@ import {
   routeOfLinkedFile,
 } from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
+import { localizeHref, servesRoute } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { extractLinks } from "../core/sources/normalize.ts";
 
 /**
- * Relative page links on the agent surfaces — the `.md`/`.mdx` mirrors,
+ * Page links on the agent surfaces — the `.md`/`.mdx` mirrors,
  * llms-full.txt, MCP `get_page` and `resources/read`. An agent resolves
  * `[Install](./install)` against the URL it fetched (`/guides.md`), so the
  * link lands on `/install`; the rendered page rewrites it to the route it
  * means (`markdown/relative-links.ts`), and the Markdown an agent reads gets
  * the same rewrite from the same resolver (`resolveRelativeHref`), so both
- * point at one page. Inline links and reference definitions are rewritten;
- * fenced and inline code, images, and anything not a relative page link are
- * left as written.
+ * point at one page. Root-relative links (`[x](/guide)`,
+ * `<Card href="/guide">`, `![logo](/logo.png)`) get what the rendered page
+ * gives them too (`markdown/base-links.ts`,
+ * `components/content/base-href.ts`): a page link the `deployment.base` +
+ * `basePath` prefix, a public file (`/spec.pdf`) or image the
+ * `deployment.base` alone, and, on a page in a prefixed locale, a page link
+ * that locale's copy of the route when it is served
+ * (`components/layout/LocaleLinks.astro`). Inline links, images, component
+ * `href`s, and reference definitions are rewritten; fenced and inline code,
+ * relative images and asset links, and external URLs are left as written.
  */
 
 /** The page a Markdown text was written for. */
@@ -47,6 +62,14 @@ const DEFINITION =
 const MAYBE_RELATIVE =
   /\]\([\t ]*<?(?![a-z][\d+.a-z-]*:|\/|#)|^ {0,3}\[[^\]\n]+\]:[\t ]*<?(?![a-z][\d+.a-z-]*:|\/|#)|\shref=["'](?![a-z][\d+.a-z-]*:|\/|#)/imu;
 
+/**
+ * {@link MAYBE_RELATIVE}, or a root-relative target (`/x`, never `//host`):
+ * the gate when root-relative links are rewritten too — a base or basePath is
+ * set, or the page sits under a locale prefix.
+ */
+const MAYBE_PAGE_LINK =
+  /\]\([\t ]*<?(?![a-z][\d+.a-z-]*:|\/\/|#)|^ {0,3}\[[^\]\n]+\]:[\t ]*<?(?![a-z][\d+.a-z-]*:|\/\/|#)|\shref=["'](?![a-z][\d+.a-z-]*:|\/\/|#)/imu;
+
 interface Splice {
   column: number;
   length: number;
@@ -82,18 +105,23 @@ const definitionSplice = (
   return { column: lead.length + angled, length: target.length, text: route };
 };
 
-/** Every routed splice in `text`, by 0-based line: links, then definitions. */
+/**
+ * Every routed splice in `text`, by 0-based line: links and images, then
+ * definitions. An image target goes through `imaged`, everything else through
+ * `routed`.
+ */
 const collectSplices = (
   text: string,
   lines: readonly string[],
-  routed: (target: string) => string | undefined
+  routed: (target: string) => string | undefined,
+  imaged: (target: string) => string | undefined
 ): Map<number, Splice[]> => {
   const splices = new Map<number, Splice[]>();
   const add = (index: number, splice: Splice): void => {
     splices.set(index, [...(splices.get(index) ?? []), splice]);
   };
   for (const link of extractLinks(text)) {
-    const route = link.image ? undefined : routed(link.target);
+    const route = (link.image ? imaged : routed)(link.target);
     if (route !== undefined) {
       add(link.line - 1, {
         column: link.column - 1,
@@ -124,7 +152,7 @@ const collectSplices = (
 export const relativeLinkRewriter = (
   project: BlumeProject
 ): RelativeLinkRewriter => {
-  const { deployment, i18n } = project.config;
+  const { basePath, deployment, i18n } = project.config;
   const deployBase = normalizeBasePath(deployment.options.base);
   const localeTokens = i18n
     ? ["$", ...i18n.locales.map((locale) => locale.code)]
@@ -137,11 +165,20 @@ export const relativeLinkRewriter = (
     ])
   );
   const routes = new Set(project.manifest.routes.map((route) => route.path));
+  const localeByRoute = new Map(
+    project.manifest.routes.map((route) => [route.path, route.locale])
+  );
 
-  return (text, page) => {
+  /**
+   * A page's relative-link resolver; `undefined` when the page has no file
+   * to resolve its links from.
+   */
+  const relativeRoute = (
+    page: LinkedPage
+  ): ((target: string) => string | undefined) | undefined => {
     const { sourcePath } = page;
-    if (!sourcePath || !MAYBE_RELATIVE.test(text)) {
-      return text;
+    if (!sourcePath) {
+      return;
     }
     const from: RelativeLinkBase = {
       isIndex: isIndexFileName(basename(sourcePath), localeTokens),
@@ -150,15 +187,62 @@ export const relativeLinkRewriter = (
     const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
     const resolveFile = (path: string): string | undefined =>
       routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
-    const routed = (target: string): string | undefined => {
+    // A resolved route is one Blume serves, so the deployment base goes on
+    // unconditionally — even over a route that starts with the base's name.
+    return (target) => {
       const route = resolveRelativeHref(target, from, resolveFile, (path) =>
         routes.has(path)
       );
-      return route === undefined ? undefined : withBasePath(deployBase, route);
+      return route === undefined ? undefined : mountBasePath(deployBase, route);
+    };
+  };
+
+  /** Whether a page is served at a based, fragment-less path. */
+  const servesPage = (route: string): boolean => servesRoute(routes, route);
+
+  return (text, page) => {
+    const locale = localeByRoute.get(page.route);
+    // The page's locale moves root links only when it has a URL prefix.
+    const localize =
+      i18n && locale !== undefined && localePrefix(locale, i18n) !== ""
+        ? { basePath, deployBase, i18n, locale, routes }
+        : undefined;
+    // A root-relative link only changes when the site is mounted under a
+    // prefix or the page reads in a prefixed locale.
+    const rootLinks =
+      deployBase !== "" || basePath !== "" || localize !== undefined;
+    if (
+      !(page.sourcePath || rootLinks) ||
+      !(rootLinks ? MAYBE_PAGE_LINK : MAYBE_RELATIVE).test(text)
+    ) {
+      return text;
+    }
+    const relative = relativeRoute(page);
+    // What the rendered page makes of `/guide`: based (a public file like
+    // `/spec.pdf` under the deployment base alone), then moved into the
+    // page's locale when that route is served.
+    const rooted = (target: string): string | undefined => {
+      const based = withAuthoredBasePath(
+        deployBase,
+        basePath,
+        target,
+        servesPage
+      );
+      const href = localize ? localizeHref(based, localize) : based;
+      return href === target ? undefined : href;
+    };
+    const routed = (target: string): string | undefined =>
+      isInternalPath(target) ? rooted(target) : relative?.(target);
+    // An image is always a file: `public/` (or a generated asset endpoint),
+    // served under the deployment base but never `basePath`. A relative one
+    // is left to `core/content-assets.ts`.
+    const imaged = (target: string): string | undefined => {
+      const based = withBasePath(deployBase, target);
+      return based === target ? undefined : based;
     };
 
     const lines = text.split("\n");
-    const splices = collectSplices(text, lines, routed);
+    const splices = collectSplices(text, lines, routed, imaged);
 
     return lines
       .map((line, index) => {

package/src/ai/serializers.ts

@@ -18,7 +18,8 @@ export const projectComponentSerializers = (
   ({
     ...exampleComponentSerializers(project.examples ?? {}),
     ...openapiComponentSerializers(
-      project.sources.find(isOpenApiSource)?.openApiData() ?? {}
+      project.sources.find(isOpenApiSource)?.openApiData() ?? {},
+      project.config.deployment.options.base
     ),
     ...project.config.agents.markdownComponents,
   }) satisfies Record<string, ComponentMarkdown>;

package/src/ai/skills.ts

@@ -151,11 +151,16 @@ const skillMeta = (raw: string, dirName: string): SkillMetaResult => {
  * hold a `SKILL.md` (the layout `npx skills add` consumes). Subdirectories
  * without one are ignored silently — the directory may hold other assets —
  * while a present-but-invalid skill earns a warning so it isn't dropped
- * behind the publisher's back.
+ * behind the publisher's back. Two directories declaring the same `name`
+ * would publish to the same artifact path under two index entries, so the
+ * first directory in sorted order keeps the name and the other is skipped
+ * with a warning naming both.
  */
 export const collectSkills = async (dir: string): Promise<CollectedSkills> => {
   const skills: SkillArtifact[] = [];
   const warnings: string[] = [];
+  /** Skill name → the directory that claimed it first. */
+  const owners = new Map<string, string>();
   const items = await readdir(dir, { withFileTypes: true });
   for (const item of items.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
     if (!item.isDirectory() || item.name.startsWith(".")) {
@@ -177,6 +182,14 @@ export const collectSkills = async (dir: string): Promise<CollectedSkills> => {
       }
       continue;
     }
+    const owner = owners.get(meta.name);
+    if (owner) {
+      warnings.push(
+        `Skills "${owner}" and "${item.name}" both declare the name "${meta.name}"; publishing "${owner}" and skipping "${item.name}".`
+      );
+      continue;
+    }
+    owners.set(meta.name, item.name);
     // A lone SKILL.md ships verbatim; supporting resources ship as an
     // archive so the skill's relative references resolve after unpacking.
     const single = entries.length === 1;

package/src/ai/static-expression.ts

@@ -0,0 +1,416 @@
+import type { EvaluatedValue } from "./component-markdown.ts";
+
+/**
+ * Read an MDX attribute expression (`prop={...}`) as literal data, without
+ * running it. The agent Markdown downleveler converts components on every
+ * page it is handed — plain `.md` pages Astro never executes, and content a
+ * CMS or a release feed supplies — so an expression is parsed, never
+ * evaluated: only data a reader could see by looking at it is recovered.
+ *
+ * Accepted: string, number, boolean, `null`, and `undefined` literals; array
+ * and object literals, nested; unary minus on a number; template literals
+ * whose substitutions are themselves accepted; and `frontmatter.<path>`
+ * member access (dot steps, or bracketed string and number literals),
+ * resolved against the page's front matter the way `prop={frontmatter.status}`
+ * resolves when Astro renders the page. Comments are skipped. Anything else —
+ * a call, an operator, a spread, a shorthand property, any other name — is
+ * not static, and the caller keeps the component's JSX as written.
+ */
+
+/** The outcome of reading an expression: its value, or `ok: false`. */
+export interface StaticExpressionResult {
+  ok: boolean;
+  value: EvaluatedValue;
+}
+
+/**
+ * Stop reading: the expression isn't literal data. The throw unwinds the
+ * recursive descent to {@link readStaticExpression}, which reports it.
+ */
+const notStatic = (): never => {
+  throw new Error("not a static expression");
+};
+
+const isText = (value: EvaluatedValue): value is string =>
+  typeof value === "string";
+
+const isNumber = (value: EvaluatedValue): value is number =>
+  typeof value === "number";
+
+/** A nested map of values: an object literal or a front-matter mapping. */
+const isValueMap = (
+  value: EvaluatedValue
+): value is { [key: string]: EvaluatedValue } =>
+  typeof value === "object" &&
+  value !== null &&
+  !Array.isArray(value) &&
+  !(value instanceof Date);
+
+/** Whitespace, a line comment, or a block comment. */
+const SPACE = /\s+|\/\/[^\n\r]*|\/\*[\s\S]*?\*\//uy;
+
+/** An IdentifierName (ASCII): object keys, member names, keywords. */
+const IDENTIFIER = /[$A-Z_a-z][\w$]*/uy;
+
+/**
+ * A numeric literal: hex, octal, and binary forms, or a decimal with an
+ * optional fraction and exponent, `_` separators allowed between digits. A
+ * legacy octal (`017`) matches only its leading `0`, and the check on the
+ * following character rejects it, as strict-mode JavaScript does.
+ */
+const NUMBER =
+  /0[Xx][\dA-Fa-f](?:_?[\dA-Fa-f])*|0[Oo][0-7](?:_?[0-7])*|0[Bb][01](?:_?[01])*|(?:(?:0|[1-9](?:_?\d)*)(?:\.(?:\d(?:_?\d)*)?)?|\.\d(?:_?\d)*)(?:[Ee][+-]?\d(?:_?\d)*)?/uy;
+
+/** A character that may not directly follow a number (`1n`, `1px`, `017`). */
+const AFTER_NUMBER = /[\w$.]/u;
+
+const DIGIT = /\d/u;
+const HEX_DIGITS = /^[\dA-Fa-f]+$/u;
+
+/** A canonical array index: `0`, `12`, never `01`. */
+const INDEX = /^(?:0|[1-9]\d*)$/u;
+
+/** The largest Unicode code point, the cap on a `\u{…}` escape. */
+const MAX_CODE_POINT = 0x10_ff_ff;
+
+/** U+2028 and U+2029, the line terminators outside ASCII. */
+const LINE_SEPARATORS = new Set([
+  String.fromCodePoint(0x20_28),
+  String.fromCodePoint(0x20_29),
+]);
+
+const SIMPLE_ESCAPES = new Map([
+  ["b", "\b"],
+  ["f", "\f"],
+  ["n", "\n"],
+  ["r", "\r"],
+  ["t", "\t"],
+  ["v", "\v"],
+]);
+
+/** A key that, set through a literal, would replace the object's prototype. */
+const PROTO_KEY = "__proto__";
+
+/**
+ * `base[key]` on a front-matter value, own data only: a missing key reads as
+ * `undefined` (as it does at render time), stepping into `null` or
+ * `undefined` is not static (it would throw), and inherited members —
+ * methods, `constructor` — are never reached.
+ */
+const member = (base: EvaluatedValue, key: string): EvaluatedValue => {
+  if (base === null || base === undefined) {
+    return notStatic();
+  }
+  if (isText(base) || Array.isArray(base)) {
+    if (key === "length") {
+      return base.length;
+    }
+    return INDEX.test(key) ? base[Number(key)] : undefined;
+  }
+  return isValueMap(base) && Object.hasOwn(base, key) ? base[key] : undefined;
+};
+
+/** A recursive-descent reader over one expression's source. */
+class Reader {
+  readonly frontmatter: Record<string, EvaluatedValue> | undefined;
+  pos = 0;
+  readonly source: string;
+
+  constructor(
+    source: string,
+    frontmatter: Record<string, EvaluatedValue> | undefined
+  ) {
+    this.source = source;
+    this.frontmatter = frontmatter;
+  }
+
+  /** The character under the cursor (`""` at the end). */
+  get char(): string {
+    return this.source.charAt(this.pos);
+  }
+
+  get done(): boolean {
+    return this.pos >= this.source.length;
+  }
+
+  /** Match a sticky pattern at the cursor and consume it. */
+  match(pattern: RegExp): string | undefined {
+    pattern.lastIndex = this.pos;
+    const found = pattern.exec(this.source)?.[0];
+    if (found !== undefined) {
+      this.pos += found.length;
+    }
+    return found;
+  }
+
+  /** Skip whitespace and comments. */
+  space(): void {
+    let skipped = this.match(SPACE);
+    while (skipped !== undefined) {
+      skipped = this.match(SPACE);
+    }
+  }
+
+  /** Consume `expected` (after any space), or stop. */
+  expect(expected: string): void {
+    this.space();
+    if (!this.source.startsWith(expected, this.pos)) {
+      notStatic();
+    }
+    this.pos += expected.length;
+  }
+
+  value(): EvaluatedValue {
+    this.space();
+    const { char } = this;
+    if (char === "{") {
+      return this.object();
+    }
+    if (char === "[") {
+      return this.array();
+    }
+    if (char === '"' || char === "'") {
+      return this.string(char);
+    }
+    if (char === "`") {
+      return this.template();
+    }
+    if (char === "-") {
+      this.pos += 1;
+      // `--1` is a decrement, not two negations.
+      const operand = this.char === "-" ? notStatic() : this.value();
+      return isNumber(operand) ? -operand : notStatic();
+    }
+    return this.number() ?? this.name();
+  }
+
+  number(): number | undefined {
+    const text = this.match(NUMBER);
+    if (text === undefined) {
+      return;
+    }
+    if (
+      AFTER_NUMBER.test(this.char) ||
+      (text === "0" && DIGIT.test(this.char))
+    ) {
+      return notStatic();
+    }
+    return Number(text.replaceAll("_", ""));
+  }
+
+  /** A keyword literal, or `frontmatter` and its member steps. */
+  name(): EvaluatedValue {
+    const name = this.match(IDENTIFIER);
+    if (name === "true") {
+      return true;
+    }
+    if (name === "false") {
+      return false;
+    }
+    if (name === "null") {
+      return null;
+    }
+    if (name === "undefined") {
+      return undefined;
+    }
+    if (name !== "frontmatter") {
+      return notStatic();
+    }
+    let current: EvaluatedValue = this.frontmatter;
+    for (;;) {
+      this.space();
+      if (this.char === ".") {
+        this.pos += 1;
+        this.space();
+        current = member(current, this.match(IDENTIFIER) ?? notStatic());
+      } else if (this.char === "[") {
+        this.pos += 1;
+        const key = this.value();
+        this.expect("]");
+        current = member(
+          current,
+          isText(key) || isNumber(key) ? String(key) : notStatic()
+        );
+      } else {
+        return current;
+      }
+    }
+  }
+
+  object(): EvaluatedValue {
+    this.pos += 1;
+    const out: { [key: string]: EvaluatedValue } = {};
+    for (;;) {
+      this.space();
+      if (this.char === "}") {
+        this.pos += 1;
+        return out;
+      }
+      const key = this.key();
+      this.expect(":");
+      out[key] = this.value();
+      this.space();
+      if (this.char === ",") {
+        this.pos += 1;
+      } else if (this.char !== "}") {
+        return notStatic();
+      }
+    }
+  }
+
+  /** An object key: a name, a string, or a number (as its canonical string). */
+  key(): string {
+    const { char } = this;
+    let key: string;
+    if (char === '"' || char === "'") {
+      key = this.string(char);
+    } else {
+      const number = this.number();
+      key =
+        number === undefined
+          ? (this.match(IDENTIFIER) ?? notStatic())
+          : String(number);
+    }
+    // `{ __proto__: … }` sets the prototype rather than a property.
+    return key === PROTO_KEY ? notStatic() : key;
+  }
+
+  array(): EvaluatedValue[] {
+    this.pos += 1;
+    const out: EvaluatedValue[] = [];
+    for (;;) {
+      this.space();
+      if (this.char === "]") {
+        this.pos += 1;
+        return out;
+      }
+      out.push(this.value());
+      this.space();
+      if (this.char === ",") {
+        this.pos += 1;
+      } else if (this.char !== "]") {
+        return notStatic();
+      }
+    }
+  }
+
+  string(quote: string): string {
+    this.pos += 1;
+    let out = "";
+    for (;;) {
+      const { char } = this;
+      if (this.done || char === "\n" || char === "\r") {
+        return notStatic();
+      }
+      this.pos += 1;
+      if (char === quote) {
+        return out;
+      }
+      out += char === "\\" ? this.escape() : char;
+    }
+  }
+
+  template(): string {
+    this.pos += 1;
+    let out = "";
+    for (;;) {
+      if (this.done) {
+        return notStatic();
+      }
+      const { char } = this;
+      this.pos += 1;
+      if (char === "`") {
+        return out;
+      }
+      if (char === "\\") {
+        out += this.escape();
+      } else if (char === "$" && this.char === "{") {
+        this.pos += 1;
+        out += String(this.value());
+        this.expect("}");
+      } else if (char === "\r") {
+        // A raw line break in a template reads as `\n`, `\r\n` included.
+        if (this.char === "\n") {
+          this.pos += 1;
+        }
+        out += "\n";
+      } else {
+        out += char;
+      }
+    }
+  }
+
+  /** What an escape after `\` stands for, under strict-mode rules. */
+  escape(): string {
+    if (this.done) {
+      return notStatic();
+    }
+    const { char } = this;
+    this.pos += 1;
+    if (DIGIT.test(char)) {
+      // `\0` is NUL; octal escapes, `\8`, and `\9` are errors in strict code.
+      return char === "0" && !DIGIT.test(this.char) ? "\0" : notStatic();
+    }
+    if (char === "x") {
+      return String.fromCodePoint(this.hex(2));
+    }
+    if (char === "u") {
+      return String.fromCodePoint(
+        this.char === "{" ? this.codePoint() : this.hex(4)
+      );
+    }
+    if (char === "\r") {
+      // A line continuation: `\` and the line break stand for nothing.
+      if (this.char === "\n") {
+        this.pos += 1;
+      }
+      return "";
+    }
+    if (char === "\n" || LINE_SEPARATORS.has(char)) {
+      return "";
+    }
+    return SIMPLE_ESCAPES.get(char) ?? char;
+  }
+
+  /** Exactly `length` hex digits, as a code point. */
+  hex(length: number): number {
+    const digits = this.source.slice(this.pos, this.pos + length);
+    if (digits.length !== length || !HEX_DIGITS.test(digits)) {
+      return notStatic();
+    }
+    this.pos += length;
+    return Number.parseInt(digits, 16);
+  }
+
+  /** A braced `\u{…}` code point, the cursor on its `{`. */
+  codePoint(): number {
+    const end = this.source.indexOf("}", this.pos);
+    const digits = end === -1 ? "" : this.source.slice(this.pos + 1, end);
+    const code = HEX_DIGITS.test(digits) ? Number.parseInt(digits, 16) : -1;
+    if (code < 0 || code > MAX_CODE_POINT) {
+      return notStatic();
+    }
+    this.pos = end + 1;
+    return code;
+  }
+}
+
+/**
+ * Read `raw` — an attribute expression's source — as static data, with
+ * `frontmatter` (the page's front matter, when the caller has it) behind
+ * `frontmatter.<path>` references. Never executes anything.
+ */
+export const readStaticExpression = (
+  raw: string,
+  frontmatter?: Record<string, EvaluatedValue>
+): StaticExpressionResult => {
+  const reader = new Reader(raw, frontmatter);
+  try {
+    const value = reader.value();
+    reader.space();
+    return reader.done ? { ok: true, value } : { ok: false, value: undefined };
+  } catch {
+    // Not literal data (or nested past the stack): keep the JSX as written.
+    return { ok: false, value: undefined };
+  }
+};