@promptbook/cli 0.114.0-4 → 0.114.0-6

package/src/book-components/Chat/utils/renderMarkdown.ts

@@ -267,14 +267,46 @@ const DETAILS_PLACEHOLDER_WRAPPED_REGEX = new RegExp(`<p>\\s*(${DETAILS_PLACEHOL
 const INLINE_REFERENCE_REGEX = /\[\[([^\]\r\n]+?)\]\]/g;
 
 /**
- * Pattern matching ordinary markdown links that can be promoted to inline reference chips.
+ * Prefix for INLINE REFERENCE PLACEHOLDER.
  *
- * Images are intentionally captured separately and left unchanged by the replacement helper.
+ * @private utility of `renderMarkdown`
+ */
+const INLINE_REFERENCE_PLACEHOLDER_PREFIX = '@@PROMPTBOOK_INLINE_REFERENCE_PLACEHOLDER__';
+
+/**
+ * Pattern matching INLINE REFERENCE PLACEHOLDER.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const INLINE_REFERENCE_PLACEHOLDER_REGEX = new RegExp(`${INLINE_REFERENCE_PLACEHOLDER_PREFIX}(\\d+)__`, 'g');
+
+/**
+ * Pattern matching markdown links and images together with their raw target.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const MARKDOWN_LINK_REGEX = /(!?)\[([^\]\r\n]*)\]\(\s*(<[^>\r\n]*>|[^()\s]+)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
+
+/**
+ * Pattern matching bare `http(s)` URLs written directly into markdown text.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const BARE_URL_REGEX = /(^|\s)(https?:\/\/[^\s<>()[\]"']+)/g;
+
+/**
+ * Sentence punctuation which trails a bare URL instead of belonging to it.
  *
  * @private utility of `renderMarkdown`
  */
-const MARKDOWN_INLINE_REFERENCE_LINK_REGEX =
-    /(!?)\[([^\]\r\n]*)\]\(\s*(<[^>\r\n]+>|[^)\s]+)(?:\s+(?:"[^"\r\n]*"|'[^'\r\n]*'|\([^)]*\)))?\s*\)/g;
+const BARE_URL_TRAILING_PUNCTUATION_REGEX = /[.,;:!?]+$/;
+
+/**
+ * Pattern splitting one URL into its scheme, host and remaining part.
+ *
+ * @private utility of `renderMarkdown`
+ */
+const ABSOLUTE_URL_REGEX = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)(.*)$/i;
 
 /**
  * Markdown patterns that are strong enough to identify content as markdown.
@@ -344,10 +376,12 @@ export type MarkdownInlineReference = {
     readonly href: string;
 
     /**
-     * Markdown link destination prefixes that should render as this reference as well.
+     * Optional URL prefixes which also identify this reference in the authored markdown.
      *
-     * This supports legacy links such as an Agents Server project file URL while keeping
-     * `reference` as the canonical `[[project]]` token.
+     * A markdown link or a bare URL pointing to one of these prefixes is rendered as the same chip
+     * as the `[[reference]]` token. Both absolute URLs (for example `https://project.example.com`)
+     * and application paths (for example `/agents/agent/projects/website`) are supported; a path
+     * prefix matches on any host so that both relative and absolute links are recognized.
      */
     readonly sourceHrefPrefixes?: ReadonlyArray<string>;
 
@@ -696,12 +730,11 @@ const CHAT_MARKDOWN_CONVERTER = createChatMarkdownConverter();
  * outer `<details>` and optional `<summary>` markup untouched.
  *
  * @param detailsBlock - Raw `<details>...</details>` HTML captured from markdown.
- * @param options - Markdown rendering options to reuse for the details body.
  * @returns `<details>` HTML whose body has been converted from markdown to HTML.
  *
  * @private utility of `renderMarkdown`
  */
-function renderDetailsBlock(detailsBlock: string, options?: RenderMarkdownOptions): string_html {
+function renderDetailsBlock(detailsBlock: string): string_html {
     const openTagMatch = detailsBlock.match(/^<details\b[^>]*>/i);
     const closeTagMatch = detailsBlock.match(/<\/details\s*>$/i);
 
@@ -715,7 +748,7 @@ function renderDetailsBlock(detailsBlock: string, options?: RenderMarkdownOption
     const summaryMatch = innerContent.match(/^(\s*<summary\b[^>]*>[\s\S]*?<\/summary\s*>)([\s\S]*)$/i);
     const summaryHtml = summaryMatch?.[1] ?? '';
     const bodyMarkdown = (summaryMatch?.[2] ?? innerContent) as string_markdown;
-    const renderedBody = renderMarkdown(bodyMarkdown, options);
+    const renderedBody = renderMarkdown(bodyMarkdown);
 
     return `${openTag}${summaryHtml}${renderedBody}${closeTag}` as string_html;
 }
@@ -759,18 +792,17 @@ function maskMarkdownCodeSegments(markdown: string_markdown): MaskedCodeSegments
  * processes their content.
  *
  * @param markdown - Markdown text that may contain raw HTML `<details>` blocks.
- * @param options - Markdown rendering options to reuse for the details body.
  * @returns Masked markdown and a restore helper that returns `string_html`.
  *
  * @private utility of `renderMarkdown`
  */
-function maskDetailsBlocks(markdown: string_markdown, options?: RenderMarkdownOptions): MaskedDetailsBlocksResult {
+function maskDetailsBlocks(markdown: string_markdown): MaskedDetailsBlocksResult {
     const blocks: string_html[] = [];
 
     DETAILS_BLOCK_REGEX.lastIndex = 0;
     const masked = markdown.replace(DETAILS_BLOCK_REGEX, (match) => {
         const placeholder = `${DETAILS_PLACEHOLDER_PREFIX}${blocks.length}__`;
-        blocks.push(renderDetailsBlock(match, options));
+        blocks.push(renderDetailsBlock(match));
         return placeholder;
     }) as string_markdown;
 
@@ -885,90 +917,181 @@ function createMarkdownInlineReferenceByKey(
 }
 
 /**
- * Returns whether a href starts with a configured source href prefix.
+ * Comparable parts of one URL used to recognize inline references written as links or bare URLs.
  *
- * @param href - Markdown link destination.
- * @param sourceHrefPrefix - Configured source href prefix.
- * @returns Whether the href belongs to the source prefix.
+ * @private utility of `renderMarkdown`
+ */
+type ComparableUrlParts = {
+    /**
+     * Lowercase host of an absolute URL, or an empty string for a host-independent application path.
+     */
+    readonly host: string;
+
+    /**
+     * Lowercase decoded path without query, hash and trailing slashes.
+     */
+    readonly path: string;
+};
+
+/**
+ * One inline reference together with its comparable source URL prefixes.
  *
  * @private utility of `renderMarkdown`
  */
-function doesHrefStartWithSourceHrefPrefix(href: string, sourceHrefPrefix: string): boolean {
-    if (href === sourceHrefPrefix) {
-        return true;
-    }
+type MarkdownInlineReferenceHrefMatcher = {
+    /**
+     * Reference rendered when one of its source prefixes matches.
+     */
+    readonly reference: MarkdownInlineReference;
 
-    const normalizedSourceHrefPrefix = sourceHrefPrefix.endsWith('/') ? sourceHrefPrefix : `${sourceHrefPrefix}/`;
+    /**
+     * Comparable form of the reference source URL prefixes.
+     */
+    readonly sourceHrefPrefixes: ReadonlyArray<ComparableUrlParts>;
+};
 
-    return href.startsWith(normalizedSourceHrefPrefix);
-}
+/**
+ * Renders one matched reference and returns the placeholder standing for it.
+ *
+ * @private utility of `renderMarkdown`
+ */
+type CreateMarkdownInlineReferencePlaceholder = (reference: MarkdownInlineReference) => string;
 
 /**
- * Returns a comparable path for an absolute href when the configured source prefix is relative.
+ * Decodes percent-encoded characters without failing on malformed input.
  *
- * @param href - Href to normalize.
- * @returns Absolute URL pathname or the original href when it is relative/invalid.
+ * @param value - Raw URL part.
+ * @returns Decoded value, or the original value when it cannot be decoded.
  *
  * @private utility of `renderMarkdown`
  */
-function resolveAbsoluteHrefPath(href: string): string {
+function decodeUrlPartSafely(value: string): string {
     try {
-        return new URL(href).pathname;
+        return decodeURIComponent(value);
     } catch {
-        return href;
+        return value;
     }
 }
 
 /**
- * Returns whether one markdown link destination belongs to one inline reference.
+ * Normalizes one URL path so that encoding, casing and trailing slashes do not break matching.
  *
- * Relative project paths also match absolute URLs on the current server, which keeps
- * server-generated relative links and model-generated absolute links consistent.
+ * @param path - Raw path including an optional query and hash.
+ * @returns Comparable path.
  *
- * @param reference - Candidate inline reference.
- * @param href - Markdown link destination.
- * @returns Whether the href should render as the reference chip.
+ * @private utility of `renderMarkdown`
+ */
+function normalizeUrlPathForComparison(path: string): string {
+    const pathWithoutQuery = path.split(/[?#]/, 1)[0] || '';
+
+    return decodeUrlPartSafely(pathWithoutQuery).toLowerCase().replace(/\/+$/, '');
+}
+
+/**
+ * Splits one absolute URL or application path into its comparable parts.
+ *
+ * @param url - Raw link target written in markdown.
+ * @returns Comparable URL parts, or `null` when the value cannot address a reference.
  *
  * @private utility of `renderMarkdown`
  */
-function doesMarkdownInlineReferenceMatchHref(reference: MarkdownInlineReference, href: string): boolean {
-    const normalizedHref = href.trim();
+function createComparableUrlParts(url: string): ComparableUrlParts | null {
+    const trimmedUrl = url
+        .trim()
+        .replace(/^<([\s\S]*)>$/, '$1')
+        .trim();
 
-    return (reference.sourceHrefPrefixes || []).some((sourceHrefPrefix) => {
-        const normalizedSourceHrefPrefix = sourceHrefPrefix.trim();
-        if (!normalizedSourceHrefPrefix) {
-            return false;
-        }
+    if (trimmedUrl === '') {
+        return null;
+    }
 
-        if (doesHrefStartWithSourceHrefPrefix(normalizedHref, normalizedSourceHrefPrefix)) {
-            return true;
-        }
+    const absoluteUrlMatch = trimmedUrl.match(ABSOLUTE_URL_REGEX);
+    if (absoluteUrlMatch) {
+        return {
+            host: absoluteUrlMatch[1]!.toLowerCase(),
+            path: normalizeUrlPathForComparison(absoluteUrlMatch[2] || ''),
+        };
+    }
 
-        const isRelativeSourceHrefPrefix = !/^[a-z][a-z0-9+.-]*:/i.test(normalizedSourceHrefPrefix);
-        const isAbsoluteHref = /^[a-z][a-z0-9+.-]*:/i.test(normalizedHref);
+    if (!trimmedUrl.startsWith('/')) {
+        return null;
+    }
 
-        return (
-            isRelativeSourceHrefPrefix &&
-            isAbsoluteHref &&
-            doesHrefStartWithSourceHrefPrefix(resolveAbsoluteHrefPath(normalizedHref), normalizedSourceHrefPrefix)
-        );
-    });
+    return {
+        host: '',
+        path: normalizeUrlPathForComparison(trimmedUrl),
+    };
 }
 
 /**
- * Finds the inline reference represented by a markdown link destination.
+ * Returns whether one URL points into one reference source prefix.
+ *
+ * @param url - Comparable parts of the link target written in markdown.
+ * @param prefix - Comparable parts of one reference source prefix.
+ * @returns `true` when the URL belongs to the reference.
  *
- * @param references - Inline references available to the markdown renderer.
- * @param href - Markdown link destination.
- * @returns Matching reference or `undefined` when the href is unrelated.
+ * @private utility of `renderMarkdown`
+ */
+function isUrlWithinReferencePrefix(url: ComparableUrlParts, prefix: ComparableUrlParts): boolean {
+    if (prefix.host !== '' && prefix.host !== url.host) {
+        return false;
+    }
+
+    if (prefix.path === '') {
+        // Note: A prefix without a path covers the whole host, a prefix without both would cover everything
+        return prefix.host !== '';
+    }
+
+    return url.path === prefix.path || url.path.startsWith(`${prefix.path}/`);
+}
+
+/**
+ * Builds matchers for references which can also be written as a markdown link or a bare URL.
+ *
+ * @param references - References available to this markdown render.
+ * @returns Matchers of references declaring at least one usable source prefix.
  *
  * @private utility of `renderMarkdown`
  */
-function findMarkdownInlineReferenceByHref(
+function createMarkdownInlineReferenceHrefMatchers(
     references: ReadonlyArray<MarkdownInlineReference>,
+): ReadonlyArray<MarkdownInlineReferenceHrefMatcher> {
+    return references
+        .map((reference) => ({
+            reference,
+            sourceHrefPrefixes: (reference.sourceHrefPrefixes || [])
+                .map((sourceHrefPrefix) => createComparableUrlParts(sourceHrefPrefix))
+                .filter((sourceHrefPrefix): sourceHrefPrefix is ComparableUrlParts => sourceHrefPrefix !== null),
+        }))
+        .filter((matcher) => matcher.sourceHrefPrefixes.length !== 0);
+}
+
+/**
+ * Finds the reference which owns one link target.
+ *
+ * @param href - Raw link target written in markdown.
+ * @param matchers - Reference matchers of this markdown render.
+ * @returns Matching reference or `null`.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function findMarkdownInlineReferenceForHref(
     href: string,
-): MarkdownInlineReference | undefined {
-    return references.find((reference) => doesMarkdownInlineReferenceMatchHref(reference, href));
+    matchers: ReadonlyArray<MarkdownInlineReferenceHrefMatcher>,
+): MarkdownInlineReference | null {
+    const urlParts = createComparableUrlParts(href);
+
+    if (urlParts === null) {
+        return null;
+    }
+
+    const matcher = matchers.find((candidateMatcher) =>
+        candidateMatcher.sourceHrefPrefixes.some((sourceHrefPrefix) =>
+            isUrlWithinReferencePrefix(urlParts, sourceHrefPrefix),
+        ),
+    );
+
+    return matcher?.reference || null;
 }
 
 /**
@@ -1042,11 +1165,113 @@ function renderMarkdownInlineReferenceMenuOptionHtml(option: MarkdownInlineRefer
 }
 
 /**
- * Replaces known `[[reference]]` tokens with link chips while leaving unknown tokens unchanged.
+ * Replaces known `[[reference]]` tokens with chip placeholders while leaving unknown tokens unchanged.
+ *
+ * @param markdown - Markdown content after code masking.
+ * @param references - References available to this markdown render.
+ * @param createPlaceholder - Renders one matched reference into a placeholder.
+ * @returns Markdown with known reference tokens replaced by placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function replaceMarkdownInlineReferenceTokens(
+    markdown: string_markdown,
+    references: ReadonlyArray<MarkdownInlineReference>,
+    createPlaceholder: CreateMarkdownInlineReferencePlaceholder,
+): string_markdown {
+    const referenceByKey = createMarkdownInlineReferenceByKey(references);
+
+    if (referenceByKey.size === 0) {
+        return markdown;
+    }
+
+    return markdown.replace(INLINE_REFERENCE_REGEX, (match, rawReference: string) => {
+        const reference = referenceByKey.get(normalizeMarkdownInlineReferenceKey(rawReference));
+
+        return reference ? createPlaceholder(reference) : match;
+    }) as string_markdown;
+}
+
+/**
+ * Replaces markdown links pointing to a known reference with chip placeholders.
+ *
+ * Images keep their original markdown so that pictures served by a reference stay visible.
+ *
+ * @param markdown - Markdown content after code masking.
+ * @param matchers - Reference matchers of this markdown render.
+ * @param createPlaceholder - Renders one matched reference into a placeholder.
+ * @returns Markdown with known reference links replaced by placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function replaceMarkdownInlineReferenceLinks(
+    markdown: string_markdown,
+    matchers: ReadonlyArray<MarkdownInlineReferenceHrefMatcher>,
+    createPlaceholder: CreateMarkdownInlineReferencePlaceholder,
+): string_markdown {
+    return markdown.replace(MARKDOWN_LINK_REGEX, (match, imageMarker: string, _label: string, rawHref: string) => {
+        if (imageMarker !== '') {
+            return match;
+        }
+
+        const reference = findMarkdownInlineReferenceForHref(rawHref, matchers);
+
+        return reference ? createPlaceholder(reference) : match;
+    }) as string_markdown;
+}
+
+/**
+ * Replaces bare URLs of known references with chip placeholders.
+ *
+ * @param markdown - Markdown content after reference links were replaced.
+ * @param matchers - Reference matchers of this markdown render.
+ * @param createPlaceholder - Renders one matched reference into a placeholder.
+ * @returns Markdown with known reference URLs replaced by placeholders.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function replaceMarkdownInlineReferenceBareUrls(
+    markdown: string_markdown,
+    matchers: ReadonlyArray<MarkdownInlineReferenceHrefMatcher>,
+    createPlaceholder: CreateMarkdownInlineReferencePlaceholder,
+): string_markdown {
+    return markdown.replace(BARE_URL_REGEX, (match, leadingWhitespace: string, rawUrl: string) => {
+        const trailingPunctuation = rawUrl.match(BARE_URL_TRAILING_PUNCTUATION_REGEX)?.[0] || '';
+        const url = rawUrl.slice(0, rawUrl.length - trailingPunctuation.length);
+        const reference = findMarkdownInlineReferenceForHref(url, matchers);
+
+        return reference ? `${leadingWhitespace}${createPlaceholder(reference)}${trailingPunctuation}` : match;
+    }) as string_markdown;
+}
+
+/**
+ * Restores chips which replaced references during the reference passes.
+ *
+ * @param markdown - Markdown containing reference placeholders.
+ * @param renderedChips - Chip HTML indexed by placeholder number.
+ * @returns Markdown with inline references rendered as HTML chips.
+ *
+ * @private utility of `renderMarkdown`
+ */
+function restoreMarkdownInlineReferenceChips(
+    markdown: string_markdown,
+    renderedChips: ReadonlyArray<string>,
+): string_markdown {
+    return markdown.replace(
+        INLINE_REFERENCE_PLACEHOLDER_REGEX,
+        (_match, index) => renderedChips[Number(index)] ?? '',
+    ) as string_markdown;
+}
+
+/**
+ * Replaces known `[[reference]]` tokens, reference links and bare reference URLs with link chips.
+ *
+ * Every matched reference is first replaced by a placeholder so that the rendered chip HTML is
+ * never processed again by a later pass.
  *
  * @param markdown - Markdown content after code masking.
  * @param options - Markdown render options.
- * @returns Markdown with known inline references rendered as HTML anchors.
+ * @returns Markdown with known inline references rendered as HTML chips.
  *
  * @private utility of `renderMarkdown`
  */
@@ -1058,33 +1283,27 @@ function applyMarkdownInlineReferences(markdown: string_markdown, options?: Rend
         return markdown;
     }
 
-    const referenceByKey = createMarkdownInlineReferenceByKey(references);
-    if (referenceByKey.size === 0) {
-        return markdown;
-    }
-
-    const markdownWithInlineReferenceTokens = markdown.replace(
-        INLINE_REFERENCE_REGEX,
-        (match, rawReference: string) => {
-            const reference = referenceByKey.get(normalizeMarkdownInlineReferenceKey(rawReference));
+    const renderedChips: Array<string> = [];
+    const createPlaceholder: CreateMarkdownInlineReferencePlaceholder = (reference) => {
+        const placeholder = `${INLINE_REFERENCE_PLACEHOLDER_PREFIX}${renderedChips.length}__`;
+        renderedChips.push(renderMarkdownInlineReferenceHtml(reference, className));
 
-            return reference ? renderMarkdownInlineReferenceHtml(reference, className) : match;
-        },
-    );
+        return placeholder;
+    };
 
-    return markdownWithInlineReferenceTokens.replace(
-        MARKDOWN_INLINE_REFERENCE_LINK_REGEX,
-        (match, imageMarker: string, _linkLabel: string, rawHref: string) => {
-            if (imageMarker) {
-                return match;
-            }
+    const hrefMatchers = createMarkdownInlineReferenceHrefMatchers(references);
+    let referencedMarkdown = replaceMarkdownInlineReferenceTokens(markdown, references, createPlaceholder);
 
-            const href = rawHref.replace(/^<|>$/g, '');
-            const reference = findMarkdownInlineReferenceByHref(references, href);
+    if (hrefMatchers.length !== 0) {
+        referencedMarkdown = replaceMarkdownInlineReferenceLinks(referencedMarkdown, hrefMatchers, createPlaceholder);
+        referencedMarkdown = replaceMarkdownInlineReferenceBareUrls(
+            referencedMarkdown,
+            hrefMatchers,
+            createPlaceholder,
+        );
+    }
 
-            return reference ? renderMarkdownInlineReferenceHtml(reference, className) : match;
-        },
-    ) as string_markdown;
+    return restoreMarkdownInlineReferenceChips(referencedMarkdown, renderedChips);
 }
 
 /**
@@ -1129,7 +1348,7 @@ export function renderMarkdown(markdown: string_markdown, options?: RenderMarkdo
 
     try {
         const normalizedMarkdown = normalizeMarkdownSublists(markdown);
-        const { masked: maskedMarkdown, restore: restoreDetails } = maskDetailsBlocks(normalizedMarkdown, options);
+        const { masked: maskedMarkdown, restore: restoreDetails } = maskDetailsBlocks(normalizedMarkdown);
         const { masked: codeMaskedMarkdown, restore: restoreCode } = maskMarkdownCodeSegments(maskedMarkdown);
         const referencedMarkdown = applyMarkdownInlineReferences(codeMaskedMarkdown, options);
         const inlineReferenceMarkdown = restoreCode(referencedMarkdown);

package/src/cli/cli-commands/coder/add.ts

@@ -102,11 +102,11 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
             const description = await resolveCoderPromptDescription(descriptionArgument);
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
 
             const { /* filePath,*/ emojiTag } = await addCoderPrompt({
                 projectPath,
@@ -117,7 +117,7 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: `${emojiTag} Add prompt`,
             });
         }),

package/src/cli/cli-commands/coder/boilerplateCount.ts

@@ -29,7 +29,7 @@ export type BoilerplateCount = {
      * Number of prompts written into each generated file.
      *
      * Note: More than one prompt per file is an advanced option - each prompt is one separate
-     *       coding task separated by `---` and tagged with its own fresh emoji tag.
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
      */
     readonly promptsPerFileCount: number;
 };