Expose FsTree, flushChanges, and printChanges from @nx/devkit for programmatic generator execution

[Fasosnql]

Summary

Currently, FsTree, flushChanges, and printChanges are internal to the nx package and cannot be imported from @nx/devkit. This means that anyone wanting to run Nx generators programmatically — without shelling out to nx generate — has no supported way to do so.

This issue proposes exposing these three symbols (plus TreeWriteOptions) as part of the public @nx/devkit API.

Current Behavior

The @nx/devkit public API only exports the Tree interface and FileChange interface (both as types). The concrete implementation FsTree and the utility functions flushChanges / printChanges are internal-only:

// packages/nx/src/devkit-exports.ts (today)
export type { Tree, FileChange } from './generators/tree';
// FsTree, flushChanges, printChanges are NOT exported

The only way to run a generator today is via exec/spawn:

// Current workaround - unsafe in agentic/scripted workflows
const { execSync } = require('child_process');
execSync('nx generate @nx/js:library my-lib', { stdio: 'inherit' });
// Files are immediately written to disk — no opportunity to inspect or validate

Alternatively, consumers import from the internal path nx/src/generators/tree, which is not a public API and subject to breaking changes without notice:

// Fragile internal import — not supported
import { FsTree, flushChanges } from 'nx/src/generators/tree';

Expected Behavior

FsTree, flushChanges, printChanges, and TreeWriteOptions should be importable from @nx/devkit:

import { FsTree, flushChanges, printChanges } from '@nx/devkit';

This enables the following programmatic workflow:

import { FsTree, flushChanges, printChanges } from '@nx/devkit';
import { libraryGenerator } from '@nx/js';

// 1. Create a tree rooted at the real workspace
const tree = new FsTree(process.cwd(), true);

// 2. Run generator function directly — no exec/spawn
await libraryGenerator(tree, { name: 'my-lib', bundler: 'tsc' });

// 3. Optionally write additional files (e.g. from LLM output)
tree.write('libs/my-lib/src/ai-generated.ts', validatedLlmOutput);

// 4. Inspect changes before committing to disk
const changes = tree.listChanges();
printChanges(changes);

// 5. Validate, then flush (or discard entirely)
if (await validateChanges(changes)) {
  flushChanges(tree.root, changes);
} else {
  console.log('Discarding changes — validation failed');
}

Motivation: LLM-Based and Agentic Code Generation

This change is particularly important for agentic and LLM-based code generation workflows, where:

1. exec/spawn is an unsafe primitive — giving an agent permission to shell out means files hit disk immediately, with no chance to review, validate, or roll back before the write occurs.
2. LLM output needs validation before disk writes — in a hybrid workflow, a generator scaffolds the structure into a virtual tree, an LLM fills in the implementation details, and a validation step (type-check, lint, test) runs against the in-memory changes before they are committed to disk.
3. Composability — programmatic generator calls can be composed in plain TypeScript scripts, combined with other async operations (API calls, LLM completions, human-in-the-loop confirmations), without needing to orchestrate multiple exec calls.

Example: LLM-Augmented Library Generation

import { FsTree, flushChanges } from '@nx/devkit';
import { libraryGenerator } from '@nx/js';
import { generateImplementation } from './my-llm-client';

async function generateSmartLibrary(name: string, description: string) {
  const tree = new FsTree(process.cwd(), false);

  // Step 1: Scaffold with Nx generator (virtual — nothing on disk yet)
  await libraryGenerator(tree, { name, bundler: 'tsc' });

  // Step 2: LLM fills in business logic
  const implementation = await generateImplementation(description);
  tree.write(`libs/${name}/src/index.ts`, implementation);

  // Step 3: Review in-memory changes
  const changes = tree.listChanges();

  // Step 4: Validate (e.g. TypeScript compile, lint)
  await validateInMemory(changes);

  // Step 5: Only now write to disk
  flushChanges(tree.root, changes);
}

This pattern is impossible today without either:

• Using unsupported internal imports (nx/src/generators/tree)
• Using exec/spawn and accepting immediate, unvalidated disk writes

Proposed Change

The change is minimal and additive — no modifications to existing code, just new exports in the public API barrel file.

File: packages/nx/src/devkit-exports.ts

- export type { Tree, FileChange } from './generators/tree';
+ export type { Tree, FileChange, TreeWriteOptions } from './generators/tree';
+ export { FsTree, flushChanges, printChanges } from './generators/tree';

Because packages/devkit/index.ts already does export * from 'nx/src/devkit-exports', no changes are needed in the @nx/devkit package itself.