@agent-native/core 0.153.10 → 0.154.1

package/corpus/templates/design/actions/import-github.ts

@@ -1,60 +1,18 @@
 import { defineAction } from "@agent-native/core";
-import { resolveSecret } from "@agent-native/core/server";
+import { collectBuilderDesignSystemGitHubFiles } from "@agent-native/core/server";
 import {
-  validateUrl,
-  parseOwnerRepo,
-  fetchGitHubJson,
-  fetchGitHubJsonResult,
-  fetchGitHubRaw,
   parseTailwindConfig,
   parseCss,
   detectStylingFramework,
-  MAX_FILES,
-  MAX_FILE_SIZE,
-  ROOT_PATTERNS,
-  SECONDARY_PATHS,
   COLOR_VAR_PATTERN,
 } from "@agent-native/core/server/design-token-utils";
 import { z } from "zod";
 
-function githubAccessError(
-  owner: string,
-  repo: string,
-  status: number,
-  hasToken: boolean,
-  message?: string,
-): Error {
-  const repoLabel = `${owner}/${repo}`;
-  const suffix = message ? ` GitHub said: ${message}` : "";
-
-  if (!hasToken && (status === 401 || status === 403 || status === 404)) {
-    return new Error(
-      `Could not access ${repoLabel}. Public repositories work without setup; private repositories require a fine-grained GitHub personal access token saved as GITHUB_TOKEN in Settings > Secrets. Limit the token to this repository and grant Repository permissions > Contents: Read-only.${suffix}`,
-    );
-  }
-
-  if (hasToken && (status === 401 || status === 403 || status === 404)) {
-    return new Error(
-      `Could not access ${repoLabel} with the saved GITHUB_TOKEN. Check that the token is not expired, the repository is selected for the token, organization SSO/approval is complete, and Repository permissions > Contents is set to Read-only.${suffix}`,
-    );
-  }
-
-  if (status === 429) {
-    return new Error(
-      `GitHub rate-limited requests for ${repoLabel}. Save a GITHUB_TOKEN in Settings > Secrets or try again after the rate limit resets.${suffix}`,
-    );
-  }
-
-  return new Error(
-    `Could not list repository contents for ${repoLabel} (GitHub returned ${status || "an error"}).${suffix}`,
-  );
-}
-
 export default defineAction({
   description:
     "Import design tokens from a GitHub repository. " +
     "Reads Tailwind configs, CSS files, theme/token files, and package.json " +
-    "to extract colors, fonts, spacing, and CSS custom properties. " +
+    "to extract colors, fonts, spacing, and CSS custom properties. Supports a pinned ref and file/folder scope. " +
     "Private repositories require a saved GITHUB_TOKEN secret; never ask users to paste a token into chat.",
   schema: z.object({
     repoUrl: z
@@ -62,103 +20,36 @@ export default defineAction({
       .describe(
         'GitHub repository URL (e.g. "https://github.com/org/repo" or "org/repo")',
       ),
+    ref: z
+      .string()
+      .trim()
+      .min(1)
+      .optional()
+      .describe("Optional branch, tag, or commit"),
+    include: z
+      .array(z.string().trim().min(1))
+      .optional()
+      .describe("Optional repository-relative files or folders to include"),
+    exclude: z
+      .array(z.string().trim().min(1))
+      .optional()
+      .describe("Optional repository-relative files or folders to exclude"),
   }),
   readOnly: true,
   http: { method: "GET" },
-  run: async ({ repoUrl }) => {
-    const { owner, repo } = parseOwnerRepo(repoUrl.trim());
-    const githubToken = await resolveSecret("GITHUB_TOKEN");
-    const githubOptions = { token: githubToken };
-
-    validateUrl(`https://api.github.com/repos/${owner}/${repo}`);
-
-    const rawFiles: Record<string, string> = {};
-    let fetchedCount = 0;
-
-    async function collectFile(path: string): Promise<void> {
-      if (fetchedCount >= MAX_FILES) return;
-      const content = await fetchGitHubRaw(owner, repo, path, githubOptions);
-      if (content) {
-        rawFiles[path] = content;
-        fetchedCount++;
-      }
-    }
-
-    // 1. List repository root
-    const rootResult = await fetchGitHubJsonResult<
-      Array<{
-        name: string;
-        type: string;
-        size?: number;
-      }>
-    >(owner, repo, "", githubOptions);
-    const rootListing = rootResult.data;
-
-    if (!rootResult.ok || !Array.isArray(rootListing)) {
-      throw githubAccessError(
-        owner,
-        repo,
-        rootResult.status,
-        !!githubToken,
-        rootResult.message,
-      );
-    }
-
-    // 2. Fetch root-level files matching patterns
-    const rootFilePromises: Promise<void>[] = [];
-    for (const entry of rootListing) {
-      if (entry.type !== "file") continue;
-      if (entry.size && entry.size > MAX_FILE_SIZE) continue;
-      const matches = ROOT_PATTERNS.some((p) => p.test(entry.name));
-      if (matches && fetchedCount < MAX_FILES) {
-        rootFilePromises.push(collectFile(entry.name));
-      }
-    }
-    await Promise.all(rootFilePromises);
-
-    // 3. Fetch secondary paths (files and directories)
-    const secondaryPromises: Promise<void>[] = [];
-    for (const path of SECONDARY_PATHS) {
-      if (fetchedCount >= MAX_FILES) break;
-
-      if (/\.\w+$/.test(path)) {
-        secondaryPromises.push(collectFile(path));
-      } else {
-        secondaryPromises.push(
-          (async () => {
-            const listing = (await fetchGitHubJson(
-              owner,
-              repo,
-              path,
-              githubOptions,
-            )) as Array<{
-              name: string;
-              type: string;
-              path: string;
-              size?: number;
-            }> | null;
-            if (!listing || !Array.isArray(listing)) return;
-            const innerPromises: Promise<void>[] = [];
-            for (const entry of listing) {
-              if (fetchedCount >= MAX_FILES) break;
-              if (entry.type !== "file") continue;
-              if (entry.size && entry.size > MAX_FILE_SIZE) continue;
-              if (
-                /\.(css|scss|less)$/.test(entry.name) ||
-                /theme/i.test(entry.name) ||
-                /tokens?/i.test(entry.name)
-              ) {
-                innerPromises.push(collectFile(entry.path));
-              }
-            }
-            await Promise.all(innerPromises);
-          })(),
-        );
-      }
-    }
-    await Promise.all(secondaryPromises);
+  run: async ({ repoUrl, ref, include, exclude }) => {
+    const collection = await collectBuilderDesignSystemGitHubFiles({
+      repoUrl: repoUrl.trim(),
+      ...(ref ? { ref } : {}),
+      ...(include ? { include } : {}),
+      ...(exclude ? { exclude } : {}),
+    });
+    const { source } = collection;
+    const rawFiles = Object.fromEntries(
+      collection.files.map(({ path, content }) => [path, content]),
+    );
 
-    // 4. Parse collected files
+    // Parse collected files
     let colors: Record<string, unknown> = {};
     let fonts: string[] = [];
     let spacing: Record<string, string> = {};
@@ -210,7 +101,10 @@ export default defineAction({
 
     return {
       source: "github" as const,
-      repoUrl: `https://github.com/${owner}/${repo}`,
+      repoUrl: source.repoUrl,
+      ...(source.ref ? { ref: source.ref } : {}),
+      ...(source.include?.length ? { include: source.include } : {}),
+      ...(source.exclude?.length ? { exclude: source.exclude } : {}),
       colors: Object.keys(colors).length > 0 ? colors : undefined,
       fonts: fonts.length > 0 ? fonts : undefined,
       spacing: Object.keys(spacing).length > 0 ? spacing : undefined,

package/corpus/templates/design/actions/index-design-system-with-builder.ts

@@ -10,7 +10,6 @@ import {
 import { z } from "zod";
 
 import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-system-proxy.js";
-import importGithub from "./import-github.js";
 
 const codeFileSchema = z.object({
   filename: z.string().trim().min(1).describe("File name or relative path"),
@@ -33,6 +32,30 @@ const codeFileSchema = z.object({
     ),
 });
 
+const githubSourceSchema = z.object({
+  repoUrl: z.string().trim().min(1).describe("GitHub repository URL"),
+  ref: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Optional branch, tag, or commit"),
+  include: z
+    .array(z.string().trim().min(1))
+    .optional()
+    .describe("Optional repository-relative files or folders to include"),
+  exclude: z
+    .array(z.string().trim().min(1))
+    .optional()
+    .describe("Optional repository-relative files or folders to exclude"),
+  instructions: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Optional indexing guidance for this repository"),
+});
+
 export default defineAction({
   description:
     "Start Builder DSI design-system indexing from connected code, a GitHub repository, code/design files, and optional design.md guidance. " +
@@ -51,7 +74,15 @@ export default defineAction({
     githubRepoUrl: z
       .string()
       .optional()
-      .describe("GitHub repository URL to index with Builder"),
+      .describe("Legacy single GitHub repository URL to index with Builder"),
+    githubSources: z
+      .array(githubSourceSchema)
+      .min(1)
+      .max(20)
+      .optional()
+      .describe(
+        "GitHub repositories to index in one design system. Each source may specify a branch/tag/commit and repository-relative files or folders.",
+      ),
     connectedProjectId: z
       .string()
       .optional()
@@ -71,21 +102,13 @@ export default defineAction({
     projectName,
     description,
     githubRepoUrl,
+    githubSources,
     connectedProjectId,
     codeFiles,
     designMd,
   }) => {
-    const githubImport = githubRepoUrl
-      ? await importGithub.run({ repoUrl: githubRepoUrl })
-      : null;
-    const githubFiles = githubImport?.rawFiles
-      ? Object.entries(githubImport.rawFiles).map(([filename, content]) => ({
-          filename,
-          content,
-        }))
-      : [];
     const files = buildBuilderDesignSystemIndexFiles({
-      codeFiles: [...(codeFiles ?? []), ...githubFiles],
+      codeFiles,
       designMd,
       // Agent action payloads intentionally stay at the core 2 MB inline
       // budget. Fail loudly instead of silently dropping a larger `.fig`;
@@ -95,10 +118,8 @@ export default defineAction({
     const result = await startBuilderDesignSystemIndex({
       projectName,
       description,
-      // Upload token-authenticated GitHub files as Builder file sources. If
-      // there was nothing relevant to upload, retain the public-repo source
-      // so public repositories still work without a saved token.
-      githubRepoUrl: githubFiles.length > 0 ? undefined : githubRepoUrl,
+      githubRepoUrl,
+      githubRepos: githubSources,
       connectedProjectId,
       files,
     });
@@ -111,12 +132,24 @@ export default defineAction({
       orgId: getRequestOrgId(),
       projectName,
       description,
+      githubSources:
+        githubSources ?? (githubRepoUrl ? [{ repoUrl: githubRepoUrl }] : []),
+      sourceKind:
+        (githubSources?.length || githubRepoUrl) &&
+        (codeFiles?.length || designMd)
+          ? "mixed"
+          : githubSources?.length || githubRepoUrl
+            ? "github"
+            : codeFiles?.length || designMd
+              ? "code"
+              : undefined,
     });
 
     return {
       ...result,
       ...proxy,
       uploadedFileCount: files.length,
+      githubSourceCount: githubSources?.length ?? (githubRepoUrl ? 1 : 0),
     };
   },
 });

package/corpus/templates/design/actions/present-design-variants.ts

@@ -46,6 +46,49 @@ const DEFAULT_RESPONSIVE_BREAKPOINTS = [MOBILE_WIDTH].map((widthPx) => ({
   prefix: widthToPrefix(widthPx),
 }));
 
+const SPECIFICATION_SIGNAL_PATTERNS = [
+  /\b(?:attached|uploaded|reference|mockup|screenshot|wireframe|source of truth|source-of-truth)\b/i,
+  /\b(?:\d+\s*[- ]\s*col(?:umn)?|grid spec|layout spec|section order|feature list)\b/i,
+  /\b(?:design system|brand system|brand kit|visual language|tokens?)\b/i,
+] as const;
+
+/**
+ * Direction summaries are useful for genuinely open-ended exploration, but
+ * the fallback renderer cannot reproduce a supplied layout or system. Keep a
+ * complete-HTML requirement at the action boundary so a model cannot turn a
+ * detailed screen brief into generic cards just by omitting `content`.
+ *
+ * The weakest of the two signals, and never the only one: `prompt` is the chat
+ * caption this same model writes for the picker, so an agent that has just
+ * decided to explore writes an exploration-flavored caption and clears the
+ * check for free. `hasLinkedDesignSystem` below is the fact the server owns.
+ */
+export function hasSpecifiedDesignPrompt(prompt?: string): boolean {
+  const value = prompt?.trim() ?? "";
+  if (!value) return false;
+  return SPECIFICATION_SIGNAL_PATTERNS.some((pattern) => pattern.test(value));
+}
+
+/**
+ * The one specification signal that survives an intake round-trip. Attachments
+ * are turn-scoped (see `ActionRunContext.attachments`), so by the time the
+ * agent asks its questions and comes back to present variants, the reference
+ * screenshot the user supplied is no longer visible to this action — but the
+ * design system they linked still is.
+ */
+async function hasLinkedDesignSystem(designId: string): Promise<boolean> {
+  const [design] = await getDb()
+    .select({ designSystemId: schema.designs.designSystemId })
+    .from(schema.designs)
+    .where(
+      and(
+        eq(schema.designs.id, designId),
+        accessFilter(schema.designs, schema.designShares),
+      ),
+    );
+  return Boolean(design?.designSystemId?.trim());
+}
+
 function hasBreakpointSet(value: unknown): boolean {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -114,7 +157,7 @@ const variantSchema = z.object({
     .string()
     .optional()
     .describe(
-      "Optional complete self-contained HTML document for this variant. Keep it compact: one representative screen or directional snapshot, not a full multi-screen app. For faster exploration, omit this and provide label/description/features; Design will generate a compact representative screen.",
+      "Complete self-contained HTML document for this variant. Keep it compact: one representative screen or directional snapshot, not a full multi-screen app. Omit it ONLY for genuinely open-ended exploration, where Design renders a generic direction card from label/description/features — that card ignores any supplied reference, layout, or design system, so omitting content is rejected when the design has a linked design system or the prompt specifies one.",
     ),
   width: z
     .number()
@@ -825,9 +868,12 @@ export default defineAction({
     "complex apps, " +
     "make each variant a " +
     "compact representative screen; pass concise labels/descriptions/features " +
-    "and omit content when full HTML would be too large. Design will render " +
-    "compact screens from the direction data. Expand the chosen direction " +
-    "after the user picks. Screens from an earlier variant set are never " +
+    "and omit content only for open-ended exploration. For a prompt with a " +
+    "specific product surface, reference, layout, or design system, provide " +
+    "complete self-contained HTML for every variant; the generic fallback is " +
+    "blocked there. Design will render compact screens from direction data only " +
+    "for open-ended exploration. Expand the chosen direction after the user " +
+    "picks. Screens from an earlier variant set are never " +
     "deleted automatically: if you are knowingly replacing your own earlier " +
     "set that the user never picked from or discussed, pass its set id in " +
     "deleteSupersededSetIds; otherwise leave old sets in place.",
@@ -872,6 +918,24 @@ export default defineAction({
   run: async ({ designId, prompt, variants, deleteSupersededSetIds }) => {
     await assertAccess("design", designId, "editor");
 
+    const omittedContent = variants.filter(
+      (variant) => !variant.content?.trim(),
+    );
+    if (
+      omittedContent.length > 0 &&
+      (hasSpecifiedDesignPrompt(prompt) ||
+        (await hasLinkedDesignSystem(designId)))
+    ) {
+      throw new Error(
+        "present-design-variants requires complete self-contained HTML for " +
+          "every variant when the design has a linked design system, or the " +
+          "prompt specifies a layout, reference, or product surface. The " +
+          "generic direction fallback ignores the brief and the system's " +
+          "tokens; use generate-design, or provide each variant's complete " +
+          "content.",
+      );
+    }
+
     // Before any mutation. These are model-authored screens created by raw
     // insert, so they need the same well-formedness gate as generate-design —
     // though not its document-shape rules, since a variant may be a sketch with
@@ -1089,7 +1153,32 @@ export default defineAction({
       editorView: "overview",
       path: `/design/${encodeURIComponent(designId)}?view=overview`,
     });
+    // The pick opens a continuation turn that inherits nothing from this one,
+    // and that turn is what expands the kept placeholder into the real screen.
+    // Without this, the expansion is design-system-blind even though the user
+    // linked one before generating.
+    const [linkedDesign] = await db
+      .select({ designSystemId: schema.designs.designSystemId })
+      .from(schema.designs)
+      .where(
+        and(
+          eq(schema.designs.id, designId),
+          accessFilter(schema.designs, schema.designShares),
+        ),
+      );
+    const variantPickContext = [
+      prompt?.trim()
+        ? `The user's original request for this design: "${prompt.trim()}". Expand the kept direction into that, not into a generic version of it.`
+        : "",
+      linkedDesign?.designSystemId
+        ? `This design is linked to design system "${linkedDesign.designSystemId}". Call \`get-design-system\` for that id and apply its tokens, typography, and usage notes while expanding the kept screen — do not substitute a generic palette or font.`
+        : "",
+    ]
+      .filter(Boolean)
+      .join("\n");
+
     await writeAppStateForCurrentTab("guided-questions", {
+      ...(variantPickContext ? { submitContext: variantPickContext } : {}),
       title: prompt ?? "Pick a direction",
       description:
         "All options are on the board. Choose one to keep; I will delete the others, read only the kept screen, and turn that direction into the final requested screen.",