fix(builders): enable directive discovery in dot-prefixed files and directories (#1228)

TooTallNate · web-flow · commit 809339ba1c83 · 2026-03-02T14:36:12.000-08:00
* fix(builders): enable directive discovery in dot-prefixed files and directories

The glob-based file scanning in getInputFiles() was using tinyglobby's
default behavior which skips dot-prefixed files/directories. This prevented
discovering files with 'use step' / 'use workflow' directives inside paths
like .config/step.ts or .hidden-workflow.ts.

Switch to relative glob patterns with per-directory cwd and dot: true to
ensure dot-files are scanned while still respecting the explicit ignore
list (.git, .next, .vercel, etc.).

* test: add E2E tests for dot-directory directive discovery

Add workbench fixtures and E2E tests verifying that 'use step' / 'use
workflow' directives inside dot-prefixed directories (.well-known/agent/)
are correctly discovered, included in manifests, and executed at runtime.

* fix: normalize paths in getInputFiles tests for Windows compatibility

tinyglobby returns forward-slash paths even on Windows, while Node's
path.join() uses backslashes. Normalize both sides to forward slashes
before comparison.

* refactor: use dirname() instead of join(.., '..') in test helper

Cleaner and more idiomatic way to get the parent directory.

* fix: add .nuxt and other build tool dot-directories to ignore list

With dot: true enabled, framework build output directories like .nuxt/
are now traversed and their generated files picked up as input files.
This caused a circular dependency in the nuxt builder where generated
.nuxt/workflow/steps.mjs was being re-discovered as an input file.

Add .nuxt, .turbo, .cache, .yarn, and .pnpm-store to the ignore list,
matching the directories already ignored by the eager builder's watcher.
diff --git a/.changeset/dot-file-directive-discovery.md b/.changeset/dot-file-directive-discovery.md
@@ -0,0 +1,5 @@
+---
+"@workflow/builders": patch
+---
+
+Enable directive discovery in dot-prefixed files and directories (e.g. `.config/step.ts`, `.hidden-workflow.ts`)
diff --git a/packages/builders/src/base-builder.ts b/packages/builders/src/base-builder.ts
@@ -97,27 +97,38 @@ export abstract class BaseBuilder {
    * and dependency directories.
    */
   protected async getInputFiles(): Promise<string[]> {
-    const patterns = this.config.dirs.map((dir) => {
-      const resolvedDir = resolve(this.config.workingDir, dir);
-      // Normalize path separators to forward slashes for glob compatibility
-      const normalizedDir = resolvedDir.replace(/\\/g, '/');
-      return `${normalizedDir}/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}`;
-    });
-
-    const result = await glob(patterns, {
-      ignore: [
-        '**/node_modules/**',
-        '**/.git/**',
-        '**/.next/**',
-        '**/.vercel/**',
-        '**/.workflow-data/**',
-        '**/.well-known/workflow/**',
-        '**/.svelte-kit/**',
-      ],
-      absolute: true,
-    });
+    const ignore = [
+      '**/node_modules/**',
+      '**/.git/**',
+      '**/.next/**',
+      '**/.nuxt/**',
+      '**/.vercel/**',
+      '**/.workflow-data/**',
+      '**/.well-known/workflow/**',
+      '**/.svelte-kit/**',
+      '**/.turbo/**',
+      '**/.cache/**',
+      '**/.yarn/**',
+      '**/.pnpm-store/**',
+    ];
+
+    // Use relative patterns with `cwd` per directory so that `dot: true`
+    // applies consistently to both the search pattern *and* the ignore
+    // patterns. When absolute patterns are used with tinyglobby, the `**`
+    // in ignore patterns does not match dot-prefixed path segments.
+    const results = await Promise.all(
+      this.config.dirs.map((dir) => {
+        const cwd = resolve(this.config.workingDir, dir);
+        return glob(['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], {
+          cwd,
+          ignore,
+          absolute: true,
+          dot: true,
+        });
+      })
+    );
 
-    return result;
+    return results.flat();
   }
 
   /**
diff --git a/packages/builders/src/get-input-files.test.ts b/packages/builders/src/get-input-files.test.ts
@@ -0,0 +1,170 @@
+import {
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { BaseBuilder } from './base-builder.js';
+import type { StandaloneConfig } from './types.js';
+
+/**
+ * Minimal subclass to expose the protected `getInputFiles()` for testing.
+ */
+class TestBuilder extends BaseBuilder {
+  async build(): Promise<void> {
+    // no-op
+  }
+
+  // Expose for tests
+  public getInputFiles(): Promise<string[]> {
+    return super.getInputFiles();
+  }
+}
+
+// Resolve symlinks in tmpdir to avoid macOS /var -> /private/var issues
+const realTmpdir = realpathSync(tmpdir());
+
+/**
+ * Normalize a path to forward slashes for cross-platform comparison.
+ * tinyglobby always returns forward-slash paths, even on Windows,
+ * while Node's `path.join()` uses backslashes on Windows.
+ */
+function normalize(p: string): string {
+  return p.replace(/\\/g, '/');
+}
+
+function writeFile(dir: string, relativePath: string, content = ''): string {
+  const fullPath = join(dir, relativePath);
+  mkdirSync(dirname(fullPath), { recursive: true });
+  writeFileSync(fullPath, content, 'utf-8');
+  return fullPath;
+}
+
+function createBuilder(workingDir: string, dirs: string[]): TestBuilder {
+  const config: StandaloneConfig = {
+    buildTarget: 'standalone',
+    workingDir,
+    dirs,
+    stepsBundlePath: join(workingDir, 'steps.js'),
+    workflowsBundlePath: join(workingDir, 'workflows.js'),
+    webhookBundlePath: join(workingDir, 'webhook.js'),
+  };
+  return new TestBuilder(config);
+}
+
+describe('getInputFiles', () => {
+  let testRoot: string;
+
+  beforeEach(() => {
+    testRoot = mkdtempSync(join(realTmpdir, 'get-input-files-'));
+  });
+
+  afterEach(() => {
+    rmSync(testRoot, { recursive: true, force: true });
+  });
+
+  it('discovers files inside dot-prefixed directories', async () => {
+    const srcDir = join(testRoot, 'src');
+    writeFile(srcDir, '.hidden/step.ts', "'use step';");
+    writeFile(srcDir, '.config/workflow.ts', "'use workflow';");
+    writeFile(srcDir, 'regular/step.ts', "'use step';");
+
+    const builder = createBuilder(testRoot, ['src']);
+    const files = (await builder.getInputFiles()).map(normalize);
+
+    expect(files).toContain(normalize(join(srcDir, '.hidden/step.ts')));
+    expect(files).toContain(normalize(join(srcDir, '.config/workflow.ts')));
+    expect(files).toContain(normalize(join(srcDir, 'regular/step.ts')));
+  });
+
+  it('discovers dot-prefixed files', async () => {
+    const srcDir = join(testRoot, 'src');
+    writeFile(srcDir, '.hidden-step.ts', "'use step';");
+    writeFile(srcDir, 'visible-step.ts', "'use step';");
+
+    const builder = createBuilder(testRoot, ['src']);
+    const files = (await builder.getInputFiles()).map(normalize);
+
+    expect(files).toContain(normalize(join(srcDir, '.hidden-step.ts')));
+    expect(files).toContain(normalize(join(srcDir, 'visible-step.ts')));
+  });
+
+  it('still excludes explicitly ignored dot-directories', async () => {
+    const srcDir = join(testRoot, 'src');
+    writeFile(srcDir, '.git/hooks/pre-commit.ts');
+    writeFile(srcDir, '.next/server/page.ts');
+    writeFile(srcDir, '.nuxt/workflow/steps.mjs');
+    writeFile(srcDir, '.vercel/output/step.ts');
+    writeFile(srcDir, '.svelte-kit/output/step.ts');
+    writeFile(srcDir, '.workflow-data/state.ts');
+    writeFile(srcDir, '.well-known/workflow/route.ts');
+    writeFile(srcDir, '.turbo/cache/build.ts');
+    writeFile(srcDir, '.cache/babel/plugin.js');
+    writeFile(srcDir, '.yarn/releases/yarn.cjs');
+    writeFile(srcDir, '.pnpm-store/v3/files.ts');
+    writeFile(srcDir, 'node_modules/pkg/index.ts');
+    // This one should still be found
+    writeFile(srcDir, '.custom/step.ts', "'use step';");
+
+    const builder = createBuilder(testRoot, ['src']);
+    const files = (await builder.getInputFiles()).map(normalize);
+
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.git/hooks/pre-commit.ts'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.next/server/page.ts'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.nuxt/workflow/steps.mjs'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.vercel/output/step.ts'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.svelte-kit/output/step.ts'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.workflow-data/state.ts'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.well-known/workflow/route.ts'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.turbo/cache/build.ts'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.cache/babel/plugin.js'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.yarn/releases/yarn.cjs'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, '.pnpm-store/v3/files.ts'))
+    );
+    expect(files).not.toContain(
+      normalize(join(srcDir, 'node_modules/pkg/index.ts'))
+    );
+    expect(files).toContain(normalize(join(srcDir, '.custom/step.ts')));
+  });
+
+  it('discovers files with various supported extensions in dot-directories', async () => {
+    const srcDir = join(testRoot, 'src');
+    writeFile(srcDir, '.api/route.tsx');
+    writeFile(srcDir, '.api/handler.mts');
+    writeFile(srcDir, '.api/utils.js');
+    writeFile(srcDir, '.api/config.cjs');
+
+    const builder = createBuilder(testRoot, ['src']);
+    const files = (await builder.getInputFiles()).map(normalize);
+
+    expect(files).toContain(normalize(join(srcDir, '.api/route.tsx')));
+    expect(files).toContain(normalize(join(srcDir, '.api/handler.mts')));
+    expect(files).toContain(normalize(join(srcDir, '.api/utils.js')));
+    expect(files).toContain(normalize(join(srcDir, '.api/config.cjs')));
+  });
+});
diff --git a/packages/core/e2e/e2e.test.ts b/packages/core/e2e/e2e.test.ts
@@ -263,6 +263,28 @@ describe('e2e', () => {
     );
   });
 
+  // Test that "use step" / "use workflow" functions inside dot-prefixed
+  // directories like `.well-known/agent/` are discovered and executed correctly.
+  // Only runs on Next.js workbenches where the test file is placed.
+  const isNextApp = process.env.APP_NAME?.includes('nextjs');
+  test.skipIf(!isNextApp)(
+    'wellKnownAgentWorkflow (.well-known/agent)',
+    { timeout: 60_000 },
+    async () => {
+      const run = await start(
+        await getWorkflowMetadata(
+          'app/.well-known/agent/v1/steps.ts',
+          'wellKnownAgentWorkflow'
+        ),
+        [5]
+      );
+
+      const returnValue = await run.returnValue;
+      // wellKnownAgentStep(5) => 5 * 2 = 10, then workflow adds 1 => 11
+      expect(returnValue).toBe(11);
+    }
+  );
+
   const isNext = process.env.APP_NAME?.includes('nextjs');
   const isLocal = deploymentUrl.includes('localhost');
   // only works with framework that transpiles react and
diff --git a/packages/core/e2e/manifest.test.ts b/packages/core/e2e/manifest.test.ts
@@ -182,6 +182,76 @@ function getStepNodes(graph: ManifestWorkflow['graph']): ManifestNode[] {
   return graph.nodes.filter((n) => n.data.stepId);
 }
 
+/**
+ * Tests that steps and workflows inside dot-prefixed directories like
+ * `.well-known/agent/` are correctly discovered and included in the manifest.
+ * This verifies the fix for tinyglobby's `dot: true` option.
+ */
+describe.each(['nextjs-webpack', 'nextjs-turbopack'])(
+  'dot-directory discovery (.well-known/agent)',
+  (project) => {
+    test(
+      `${project}: discovers steps inside .well-known/agent directory`,
+      { timeout: 30_000 },
+      async () => {
+        if (process.env.APP_NAME && project !== process.env.APP_NAME) {
+          return;
+        }
+
+        const manifest = await tryReadManifest(project);
+        if (!manifest) return;
+
+        // Find the step from .well-known/agent/v1/steps.ts
+        const stepFiles = Object.keys(manifest.steps);
+        const wellKnownStepFile = stepFiles.find(
+          (f) =>
+            f.includes('.well-known/agent') || f.includes('well-known/agent')
+        );
+        expect(
+          wellKnownStepFile,
+          `Expected a step file matching ".well-known/agent" in manifest steps. Available: ${stepFiles.join(', ')}`
+        ).toBeDefined();
+
+        const fileSteps = manifest.steps[wellKnownStepFile!];
+        expect(fileSteps.wellKnownAgentStep).toBeDefined();
+        expect(fileSteps.wellKnownAgentStep.stepId).toContain(
+          'wellKnownAgentStep'
+        );
+      }
+    );
+
+    test(
+      `${project}: discovers workflows inside .well-known/agent directory`,
+      { timeout: 30_000 },
+      async () => {
+        if (process.env.APP_NAME && project !== process.env.APP_NAME) {
+          return;
+        }
+
+        const manifest = await tryReadManifest(project);
+        if (!manifest) return;
+
+        // Find the workflow from .well-known/agent/v1/steps.ts
+        const workflowFiles = Object.keys(manifest.workflows);
+        const wellKnownWorkflowFile = workflowFiles.find(
+          (f) =>
+            f.includes('.well-known/agent') || f.includes('well-known/agent')
+        );
+        expect(
+          wellKnownWorkflowFile,
+          `Expected a workflow file matching ".well-known/agent" in manifest workflows. Available: ${workflowFiles.join(', ')}`
+        ).toBeDefined();
+
+        const fileWorkflows = manifest.workflows[wellKnownWorkflowFile!];
+        expect(fileWorkflows.wellKnownAgentWorkflow).toBeDefined();
+        expect(fileWorkflows.wellKnownAgentWorkflow.workflowId).toContain(
+          'wellKnownAgentWorkflow'
+        );
+      }
+    );
+  }
+);
+
 /**
  * Tests for single-statement control flow extraction.
  * These verify that steps inside if/while/for without braces are extracted.
diff --git a/workbench/nextjs-turbopack/app/.well-known/agent/v1/steps.ts b/workbench/nextjs-turbopack/app/.well-known/agent/v1/steps.ts
@@ -0,0 +1,18 @@
+/**
+ * Test file for verifying that workflow discovers step/workflow functions
+ * inside dot-prefixed directories like `.well-known/agent/`.
+ *
+ * This simulates the pattern used by agent frameworks that place generated
+ * step functions inside `app/.well-known/agent/v1/steps.ts`.
+ */
+
+export async function wellKnownAgentStep(input: number) {
+  'use step';
+  return input * 2;
+}
+
+export async function wellKnownAgentWorkflow(value: number) {
+  'use workflow';
+  const result = await wellKnownAgentStep(value);
+  return result + 1;
+}
diff --git a/workbench/nextjs-turbopack/app/api/chat/route.ts b/workbench/nextjs-turbopack/app/api/chat/route.ts
@@ -1,8 +1,11 @@
 // THIS FILE IS JUST FOR TESTING HMR AS AN ENTRY NEEDS
 // TO IMPORT THE WORKFLOWS TO DISCOVER THEM AND WATCH
+
+// Test that steps inside dot-prefixed directories are discovered
+import * as wellKnownAgentSteps from '@/app/.well-known/agent/v1/steps';
 import * as workflows from '@/workflows/3_streams';
 
 export async function POST(_req: Request) {
-  console.log(workflows);
+  console.log(workflows, wellKnownAgentSteps);
   return Response.json('hello world');
 }
diff --git a/workbench/nextjs-webpack/app/.well-known/agent/v1/steps.ts b/workbench/nextjs-webpack/app/.well-known/agent/v1/steps.ts
@@ -0,0 +1,18 @@
+/**
+ * Test file for verifying that workflow discovers step/workflow functions
+ * inside dot-prefixed directories like `.well-known/agent/`.
+ *
+ * This simulates the pattern used by agent frameworks that place generated
+ * step functions inside `app/.well-known/agent/v1/steps.ts`.
+ */
+
+export async function wellKnownAgentStep(input: number) {
+  'use step';
+  return input * 2;
+}
+
+export async function wellKnownAgentWorkflow(value: number) {
+  'use workflow';
+  const result = await wellKnownAgentStep(value);
+  return result + 1;
+}
diff --git a/workbench/nextjs-webpack/app/api/chat/route.ts b/workbench/nextjs-webpack/app/api/chat/route.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@workflow/builders": patch
 +---
++
 +Enable directive discovery in dot-prefixed files and directories (e.g. `.config/step.ts`, `.hidden-workflow.ts`)