@baseplate-dev/project-builder-cli 0.3.3 → 0.3.4

package/dist/commands/dev-server.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function addDevServerCommand(program: Command): void;

package/dist/commands/dev-server.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { createServiceActionContext } from '#src/utils/create-service-action-context.js';
+import { logger } from '../services/logger.js';
+export function addDevServerCommand(program) {
+    program
+        .command('dev-server')
+        .description('Start the development server with MCP integration')
+        .option('-c, --current-dir <path>', 'Current directory (default: process.cwd())')
+        .action(async (options) => {
+        const cwd = options.currentDir
+            ? path.resolve(options.currentDir)
+            : process.cwd();
+        logger.info('Starting Baseplate development server...', {
+            cwd,
+        });
+        const context = await createServiceActionContext();
+        const { DevServer } = await import('@baseplate-dev/project-builder-server/dev-server');
+        const devServer = new DevServer({
+            cwd,
+            context,
+        });
+        await devServer.start();
+    });
+}

package/dist/commands/diff.js

@@ -1,35 +1,23 @@
-import { createSchemaParserContext } from '#src/services/schema-parser-context.js';
-import { getUserConfig } from '#src/services/user-config.js';
-import { expandPathWithTilde } from '#src/utils/path.js';
-import { logger } from '../services/logger.js';
+import { diffProjectAction, invokeServiceActionAsCli, } from '@baseplate-dev/project-builder-server/actions';
+import { createServiceActionContext } from '#src/utils/create-service-action-context.js';
+import { resolveProject } from '#src/utils/list-projects.js';
 /**
  * Adds a diff command to the program.
  * @param program - The program to add the command to.
  */
 export function addDiffCommand(program) {
     program
-        .command('diff [directory]')
-        .description('Show diff between generated output and current working directory')
+        .command('diff [project]')
+        .description('Show diff between generated output and project (name or directory)')
         .option('--compact', 'Show compact diff format instead of unified diff')
-        .option('--app <apps...>', 'Filter by specific app names')
-        .option('--glob <patterns...>', 'Filter files by glob patterns')
-        .option('--no-ignore-file', 'Disable .baseplateignore file filtering')
-        .action(async (directory, options) => {
-        const { diffProject } = await import('@baseplate-dev/project-builder-server');
-        const resolvedDirectory = directory
-            ? expandPathWithTilde(directory)
-            : process.cwd();
-        const context = await createSchemaParserContext(resolvedDirectory);
-        const userConfig = await getUserConfig();
-        await diffProject({
-            directory: resolvedDirectory,
-            logger,
-            context,
-            userConfig,
-            compact: options.compact ?? false,
-            appFilter: options.app,
-            globPatterns: options.glob,
-            useIgnoreFile: options.ignoreFile ?? true,
-        });
+        .option('--package <packages...>', 'Filter by specific package names')
+        .option('--include <patterns...>', 'Filter files by glob patterns')
+        .action(async (project, options) => {
+        const resolvedProject = await resolveProject(project);
+        const context = await createServiceActionContext(resolvedProject);
+        await invokeServiceActionAsCli(diffProjectAction, {
+            project: resolvedProject.name,
+            ...options,
+        }, context);
     });
 }

package/dist/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function addMcpCommand(program: Command): void;

package/dist/commands/mcp.js

@@ -0,0 +1,11 @@
+import { createServiceActionContext } from '#src/utils/create-service-action-context.js';
+export function addMcpCommand(program) {
+    program
+        .command('mcp')
+        .description('Start the MCP server in stdio mode')
+        .action(async () => {
+        const context = await createServiceActionContext();
+        const { startMcpStdioServer } = await import('@baseplate-dev/project-builder-server/dev-server');
+        await startMcpStdioServer(context);
+    });
+}

package/dist/commands/projects.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+/**
+ * Adds project management commands to the program.
+ * @param program - The program to add the commands to.
+ */
+export declare function addProjectsCommand(program: Command): void;

package/dist/commands/projects.js

@@ -0,0 +1,91 @@
+import { resolveProjects } from '../utils/project-resolver.js';
+/**
+ * Adds project management commands to the program.
+ * @param program - The program to add the commands to.
+ */
+export function addProjectsCommand(program) {
+    const projectsCommand = program
+        .command('projects')
+        .description('Manage and discover projects');
+    // Projects list subcommand
+    projectsCommand
+        .command('list')
+        .description('List all available projects')
+        .option('--json', 'Output in JSON format', false)
+        .option('--include-examples', 'Include example projects (overrides INCLUDE_EXAMPLES env)', undefined)
+        .action(async (options) => {
+        await handleListProjects(options);
+    });
+}
+async function handleListProjects(options) {
+    try {
+        const projectMap = await resolveProjects({
+            includeExamples: options.includeExamples ?? process.env.INCLUDE_EXAMPLES === 'true',
+            defaultToCwd: true,
+        });
+        if (projectMap.size === 0) {
+            console.info('No projects found.');
+            console.info('Try setting PROJECT_DIRECTORIES or INCLUDE_EXAMPLES=true environment variables.');
+            return;
+        }
+        if (options.json) {
+            const projects = [...projectMap.values()].map((project) => ({
+                name: project.name,
+                path: project.path,
+                isExample: project.isExample,
+                description: project.packageJson.description ?? null,
+                version: project.packageJson.version ?? null,
+            }));
+            console.info(JSON.stringify(projects, null, 2));
+        }
+        else {
+            console.info(`Found ${projectMap.size} project(s):\n`);
+            // Group projects by type
+            const examples = [];
+            const regular = [];
+            for (const project of projectMap.values()) {
+                if (project.isExample) {
+                    examples.push(project);
+                }
+                else {
+                    regular.push(project);
+                }
+            }
+            // Display regular projects first
+            if (regular.length > 0) {
+                console.info('📦 Projects:');
+                for (const project of regular) {
+                    console.info(`   ${project.name}`);
+                    if (typeof project.packageJson.description === 'string') {
+                        console.info(`     ${project.packageJson.description}`);
+                    }
+                    console.info(`     Path: ${project.path}`);
+                    console.info();
+                }
+            }
+            // Display examples
+            if (examples.length > 0) {
+                console.info('📚 Examples:');
+                for (const project of examples) {
+                    console.info(`   ${project.name}`);
+                    if (typeof project.packageJson.description === 'string') {
+                        console.info(`     ${project.packageJson.description}`);
+                    }
+                    console.info(`     Path: ${project.path}`);
+                    console.info();
+                }
+            }
+            console.info('Usage examples:');
+            console.info('  pnpm baseplate serve <project-name>');
+            console.info('  pnpm baseplate diff <project-name>');
+            console.info('  pnpm baseplate templates extract <project-name> <app>');
+            console.info();
+            console.info('Tip: Set INCLUDE_EXAMPLES=true to automatically include example projects');
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to list projects: ${errorMessage}`);
+        throw error;
+    }
+}

package/dist/commands/server.js

@@ -1,9 +1,10 @@
-import { getDefaultPlugins } from '@baseplate-dev/project-builder-common';
+import { discoverProjects } from '@baseplate-dev/project-builder-server/actions';
 import path from 'node:path';
 import { packageDirectory } from 'pkg-dir';
 import { getUserConfig } from '#src/services/user-config.js';
 import { getEnabledFeatureFlags } from '../services/feature-flags.js';
 import { logger } from '../services/logger.js';
+import { createServiceActionContext } from '../utils/create-service-action-context.js';
 import { expandPathWithTilde } from '../utils/path.js';
 import { resolveModule } from '../utils/resolve.js';
 import { getPackageVersion } from '../utils/version.js';
@@ -12,25 +13,27 @@ export async function serveWebServer(directories, { browser, port, logger: overr
     const projectBuilderWebDir = await packageDirectory({
         cwd: resolveModule('@baseplate-dev/project-builder-web/package.json'),
     });
-    const resolvedDirectories = directories.map((dir) => expandPathWithTilde(dir));
-    const builtInPlugins = await getDefaultPlugins(logger);
     const version = await getPackageVersion();
     if (!projectBuilderWebDir) {
         throw new Error(`Unable to find project-builder-web package to host website`);
     }
     const userConfig = await getUserConfig();
+    const context = await createServiceActionContext();
     const serviceManager = new BuilderServiceManager({
-        initialDirectories: resolvedDirectories,
         cliVersion: version,
-        builtInPlugins,
-        userConfig,
         skipCommands,
         cliFilePath: process.argv[1],
+        serviceActionContext: context,
     });
+    // Apply PORT_OFFSET if set
+    const portOffset = process.env.PORT_OFFSET
+        ? Number.parseInt(process.env.PORT_OFFSET, 10)
+        : 0;
+    const effectivePort = port ?? DEFAULT_SERVER_PORT + portOffset;
     const fastifyInstance = await startWebServer({
         serviceManager,
         browser,
-        port: port ?? DEFAULT_SERVER_PORT,
+        port: effectivePort,
         cliVersion: version,
         projectBuilderStaticDir: path.join(projectBuilderWebDir, 'dist'),
         logger: overrideLogger ?? logger,
@@ -49,8 +52,24 @@ export function addServeCommand(program) {
         .option('--browser', 'Opens browser with project builder web service', !process.env.NO_BROWSER || process.env.NO_BROWSER === 'false')
         .option('--no-browser', 'Do not start browser')
         .option('--port <number>', 'Port to listen on', Number.parseInt, process.env.PORT ? Number.parseInt(process.env.PORT, 10) : undefined)
-        .argument('[directories...]', 'Directories to serve', process.env.PROJECT_DIRECTORIES?.split(',') ?? ['.'])
-        .action(async (directories, { browser, port }) => {
-        await serveWebServer(directories, { browser, port });
+        .argument('[projects...]', 'Project names or directories to serve', process.env.PROJECT_DIRECTORIES?.split(',') ?? ['.'])
+        .action(async (projects, { browser, port }) => {
+        try {
+            // Resolve directories and discover projects
+            const resolvedDirectories = projects.length > 0
+                ? projects.map((dir) => expandPathWithTilde(dir))
+                : [process.cwd()];
+            const discoveredProjects = await discoverProjects(resolvedDirectories, logger);
+            const projectDirectories = discoveredProjects.map((p) => p.directory);
+            const projectNames = discoveredProjects.map((p) => p.name);
+            if (projectNames.length > 0) {
+                logger.info(`Serving ${projectNames.length} project(s): ${projectNames.join(', ')}`);
+            }
+            await serveWebServer(projectDirectories, { browser, port });
+        }
+        catch (error) {
+            logger.error(`Failed to resolve projects: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
     });
 }

package/dist/commands/snapshot.js

@@ -2,6 +2,7 @@ import { confirm } from '@inquirer/prompts';
 import { createSchemaParserContext } from '#src/services/schema-parser-context.js';
 import { getUserConfig } from '#src/services/user-config.js';
 import { expandPathWithTilde } from '#src/utils/path.js';
+import { resolveProject } from '#src/utils/project-resolver.js';
 import { logger } from '../services/logger.js';
 /**
  * Adds snapshot management commands to the program.
@@ -13,14 +14,24 @@ export function addSnapshotCommand(program) {
         .description('Manage project snapshots for persistent differences');
     // snapshot add command
     snapshotCommand
-        .command('add <project-directory> <app> <files...>')
+        .command('add <project> <app> <files...>')
         .description('Add files to snapshot (use --deleted for intentionally deleted files)')
         .option('--deleted', 'Mark files as intentionally deleted in snapshot')
         .option('--snapshot-dir <directory>', 'Snapshot directory', '.baseplate-snapshot')
-        .action(async (projectDirectory, app, files, options) => {
+        .action(async (project, app, files, options) => {
         try {
             const { addFilesToSnapshot } = await import('@baseplate-dev/project-builder-server');
-            const resolvedDirectory = expandPathWithTilde(projectDirectory);
+            let resolvedDirectory;
+            if (project.includes('/') || project.includes('\\')) {
+                // It's a path, expand it
+                resolvedDirectory = expandPathWithTilde(project);
+            }
+            else {
+                // It's a project name, resolve it
+                const projectInfo = await resolveProject(project);
+                resolvedDirectory = projectInfo.path;
+                logger.info(`Running snapshot add for project: ${projectInfo.name}`);
+            }
             const context = await createSchemaParserContext(resolvedDirectory);
             await addFilesToSnapshot(files, !!options.deleted, {
                 projectDirectory: resolvedDirectory,
@@ -37,13 +48,23 @@ export function addSnapshotCommand(program) {
     });
     // snapshot remove command
     snapshotCommand
-        .command('remove <project-directory> <app> <files...>')
+        .command('remove <project> <app> <files...>')
         .description('Remove files from snapshot tracking')
         .option('--snapshot-dir <directory>', 'Snapshot directory', '.baseplate-snapshot')
-        .action(async (projectDirectory, app, files, options) => {
+        .action(async (project, app, files, options) => {
         try {
             const { removeFilesFromSnapshot } = await import('@baseplate-dev/project-builder-server');
-            const resolvedDirectory = expandPathWithTilde(projectDirectory);
+            let resolvedDirectory;
+            if (project.includes('/') || project.includes('\\')) {
+                // It's a path, expand it
+                resolvedDirectory = expandPathWithTilde(project);
+            }
+            else {
+                // It's a project name, resolve it
+                const projectInfo = await resolveProject(project);
+                resolvedDirectory = projectInfo.path;
+                logger.info(`Running snapshot remove for project: ${projectInfo.name}`);
+            }
             const context = await createSchemaParserContext(resolvedDirectory);
             await removeFilesFromSnapshot(files, {
                 projectDirectory: resolvedDirectory,
@@ -60,13 +81,23 @@ export function addSnapshotCommand(program) {
     });
     // snapshot save command
     snapshotCommand
-        .command('save <project-directory> <app>')
+        .command('save <project> <app>')
         .description('Save snapshot of current differences (overwrites existing snapshot)')
         .option('--snapshot-dir <directory>', 'Snapshot directory', '.baseplate-snapshot')
-        .action(async (projectDirectory, app, options) => {
+        .action(async (project, app, options) => {
         try {
             const { createSnapshotForProject } = await import('@baseplate-dev/project-builder-server');
-            const resolvedDirectory = expandPathWithTilde(projectDirectory);
+            let resolvedDirectory;
+            if (project.includes('/') || project.includes('\\')) {
+                // It's a path, expand it
+                resolvedDirectory = expandPathWithTilde(project);
+            }
+            else {
+                // It's a project name, resolve it
+                const projectInfo = await resolveProject(project);
+                resolvedDirectory = projectInfo.path;
+                logger.info(`Running snapshot save for project: ${projectInfo.name}`);
+            }
             const context = await createSchemaParserContext(resolvedDirectory);
             const userConfig = await getUserConfig();
             // Confirm with user before overwriting existing snapshot
@@ -97,13 +128,23 @@ export function addSnapshotCommand(program) {
     });
     // snapshot show command
     snapshotCommand
-        .command('show <project-directory> <app>')
+        .command('show <project> <app>')
         .description('Show current snapshot contents')
         .option('--snapshot-dir <directory>', 'Snapshot directory', '.baseplate-snapshot')
-        .action(async (projectDirectory, app, options) => {
+        .action(async (project, app, options) => {
         try {
             const { listSnapshotContents } = await import('@baseplate-dev/project-builder-server');
-            const resolvedDirectory = expandPathWithTilde(projectDirectory);
+            let resolvedDirectory;
+            if (project.includes('/') || project.includes('\\')) {
+                // It's a path, expand it
+                resolvedDirectory = expandPathWithTilde(project);
+            }
+            else {
+                // It's a project name, resolve it
+                const projectInfo = await resolveProject(project);
+                resolvedDirectory = projectInfo.path;
+                logger.info(`Running snapshot show for project: ${projectInfo.name}`);
+            }
             const context = await createSchemaParserContext(resolvedDirectory);
             await listSnapshotContents({
                 projectDirectory: resolvedDirectory,

package/dist/commands/sync.js

@@ -1,46 +1,26 @@
-import { createSchemaParserContext } from '#src/services/schema-parser-context.js';
-import { getUserConfig } from '#src/services/user-config.js';
-import { expandPathWithTilde } from '#src/utils/path.js';
-import { logger } from '../services/logger.js';
+import { invokeServiceActionAsCli, syncProjectAction, } from '@baseplate-dev/project-builder-server/actions';
+import { createServiceActionContext } from '#src/utils/create-service-action-context.js';
 /**
  * Adds a sync command to the program.
  * @param program - The program to add the command to.
  */
 export function addSyncCommand(program) {
     program
-        .command('sync [directory]')
+        .command('sync [project]')
         .description('Syncs project from project-definition.json in baseplate/ directory')
         .option('--overwrite', 'Force overwrite existing files and apply snapshots automatically')
         .option('--snapshot <directory>', 'Apply diffs from snapshot directory (requires --overwrite)')
-        .action(async (directory, options) => {
-        const { syncProject, SyncMetadataController } = await import('@baseplate-dev/project-builder-server');
-        const resolvedDirectory = directory
-            ? expandPathWithTilde(directory)
-            : '.';
-        // Validate that --snapshot requires --overwrite
-        if (options.snapshot && !options.overwrite) {
-            logger.error('Error: --snapshot option requires --overwrite flag');
-            logger.error('Snapshots are only applied when overwriting files, not during normal merging.');
-            throw new Error('--snapshot option requires --overwrite flag');
-        }
-        const context = await createSchemaParserContext(resolvedDirectory);
-        const userConfig = await getUserConfig();
-        const syncMetadataController = new SyncMetadataController(resolvedDirectory, logger);
-        try {
-            await syncProject({
-                directory: resolvedDirectory,
-                logger,
-                context,
-                userConfig,
-                cliFilePath: process.argv[1],
-                syncMetadataController,
-                overwrite: options.overwrite ?? false,
-                snapshotDirectory: options.overwrite ? options.snapshot : undefined,
-            });
-        }
-        catch (error) {
-            logger.error('Sync failed:', error);
-            throw error;
+        .action(async (project, options) => {
+        const context = await createServiceActionContext();
+        const projectWithDefault = project ??
+            (context.projects.length > 0 ? context.projects[0].name : undefined);
+        if (!projectWithDefault) {
+            throw new Error('No project specified');
         }
+        await invokeServiceActionAsCli(syncProjectAction, {
+            project: projectWithDefault,
+            overwrite: options.overwrite,
+            snapshotDirectory: options.snapshot,
+        }, context);
     });
 }

package/dist/commands/templates.js

@@ -2,6 +2,7 @@ import { getDefaultPlugins } from '@baseplate-dev/project-builder-common';
 import path from 'node:path';
 import { logger } from '#src/services/logger.js';
 import { expandPathWithTilde } from '#src/utils/path.js';
+import { resolveProject } from '#src/utils/project-resolver.js';
 /**
  * Adds template management commands to the program.
  * @param program - The program to add the commands to.
@@ -29,12 +30,12 @@ export function addTemplatesCommand(program) {
     });
     // Templates extract subcommand
     templatesCommand
-        .command('extract <directory> <app>')
-        .description('Extracts templates from the specified directory and saves them to the templates directory')
+        .command('extract <project> <app>')
+        .description('Extracts templates from the specified project (name or directory) and saves them to the templates directory')
         .option('--auto-generate-extractor', 'Auto-generate extractor.json files', true)
         .option('--skip-clean', 'Skip cleaning the output directories (templates and generated)', false)
-        .action(async (directory, app, options) => {
-        await handleExtractTemplates(directory, app, options);
+        .action(async (project, app, options) => {
+        await handleExtractTemplates(project, app, options);
     });
     // Templates generate subcommand
     templatesCommand
@@ -107,14 +108,21 @@ async function handleDeleteTemplate(generatorName, templateName, options) {
         throw error;
     }
 }
-async function handleExtractTemplates(directory, app, options) {
-    const { runTemplateExtractorsForProject } = await import('@baseplate-dev/project-builder-server/template-extractor');
-    const resolvedDirectory = expandPathWithTilde(directory);
-    const defaultPlugins = await getDefaultPlugins(logger);
-    await runTemplateExtractorsForProject(resolvedDirectory, app, defaultPlugins, logger, {
-        autoGenerateExtractor: options.autoGenerateExtractor,
-        skipClean: options.skipClean,
-    });
+async function handleExtractTemplates(project, app, options) {
+    try {
+        const { runTemplateExtractorsForProject } = await import('@baseplate-dev/project-builder-server/template-extractor');
+        const projectInfo = await resolveProject(project);
+        const defaultPlugins = await getDefaultPlugins(logger);
+        logger.info(`Extracting templates from project: ${projectInfo.name}`);
+        await runTemplateExtractorsForProject(projectInfo.path, app, defaultPlugins, logger, {
+            autoGenerateExtractor: options.autoGenerateExtractor,
+            skipClean: options.skipClean,
+        });
+    }
+    catch (error) {
+        logger.error(`Failed to extract templates: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
 }
 async function handleGenerateTemplates(directory, options) {
     const { generateTypedTemplateFiles } = await import('@baseplate-dev/project-builder-server/template-extractor');

package/dist/index.js

@@ -1,6 +1,9 @@
 import { program } from 'commander';
 import { addConfigCommand } from './commands/config.js';
+import { addDevServerCommand } from './commands/dev-server.js';
 import { addDiffCommand } from './commands/diff.js';
+import { addMcpCommand } from './commands/mcp.js';
+import { addProjectsCommand } from './commands/projects.js';
 import { addServeCommand } from './commands/server.js';
 import { addSnapshotCommand } from './commands/snapshot.js';
 import { addSyncCommand } from './commands/sync.js';
@@ -22,6 +25,9 @@ export async function runCli() {
     addSyncCommand(program);
     addDiffCommand(program);
     addServeCommand(program);
+    addDevServerCommand(program);
+    addProjectsCommand(program);
     addConfigCommand(program);
+    addMcpCommand(program);
     await program.parseAsync(process.argv);
 }

package/dist/services/user-config.d.ts

@@ -1,4 +1,4 @@
-import type { BaseplateUserConfig } from '@baseplate-dev/project-builder-server';
+import type { BaseplateUserConfig } from '@baseplate-dev/project-builder-server/user-config';
 /**
  * Get the user config for the project builder.
  *

package/dist/services/user-config.js

@@ -1,3 +1,4 @@
+import { userConfigSchema } from '@baseplate-dev/project-builder-server/user-config';
 import { handleFileNotFoundError, readJsonWithSchema, writeStablePrettyJson, } from '@baseplate-dev/utils/node';
 import { mkdir } from 'node:fs/promises';
 import os from 'node:os';
@@ -12,7 +13,6 @@ function getConfigPath() {
  * @returns The user config for the project builder.
  */
 export async function getUserConfig() {
-    const { userConfigSchema } = await import('@baseplate-dev/project-builder-server');
     const configPath = getConfigPath();
     const config = await readJsonWithSchema(configPath, userConfigSchema).catch(handleFileNotFoundError);
     return config ?? {};

package/dist/utils/config.d.ts

@@ -0,0 +1,14 @@
+import z from 'zod';
+declare const envConfigSchema: z.ZodObject<{
+    PROJECT_DIRECTORIES: z.ZodOptional<z.ZodString>;
+    INCLUDE_EXAMPLES: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    PROJECT_DIRECTORIES?: string | undefined;
+    INCLUDE_EXAMPLES?: boolean | undefined;
+}, {
+    PROJECT_DIRECTORIES?: string | undefined;
+    INCLUDE_EXAMPLES?: boolean | undefined;
+}>;
+type EnvConfig = z.infer<typeof envConfigSchema>;
+export declare function getEnvConfig(): EnvConfig;
+export {};

package/dist/utils/config.js

@@ -0,0 +1,8 @@
+import z from 'zod';
+const envConfigSchema = z.object({
+    PROJECT_DIRECTORIES: z.string().optional(),
+    INCLUDE_EXAMPLES: z.coerce.boolean().optional(),
+});
+export function getEnvConfig() {
+    return envConfigSchema.parse(process.env);
+}

package/dist/utils/create-service-action-context.d.ts

@@ -0,0 +1,2 @@
+import type { ServiceActionContext, ServiceActionProject } from '@baseplate-dev/project-builder-server/actions';
+export declare function createServiceActionContext(project?: ServiceActionProject): Promise<ServiceActionContext>;

package/dist/utils/create-service-action-context.js

@@ -0,0 +1,15 @@
+import { getDefaultPlugins } from '@baseplate-dev/project-builder-common';
+import { logger } from '#src/services/logger.js';
+import { getUserConfig } from '#src/services/user-config.js';
+import { listProjects } from './list-projects.js';
+export async function createServiceActionContext(project) {
+    const projects = project ? [project] : await listProjects({});
+    const plugins = await getDefaultPlugins(logger);
+    const userConfig = await getUserConfig();
+    return {
+        projects,
+        logger,
+        userConfig,
+        plugins,
+    };
+}

package/dist/utils/find-examples-directories.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Find all example directories in the Baseplate repository.
+ *
+ * This function locates the root of the Baseplate monorepo by finding the current
+ * package's package.json, then navigating up to find the root package.json with
+ * name "@baseplate-dev/root". It then looks for directories in the examples/ folder.
+ *
+ * @returns Array of absolute paths to example directories
+ * @throws Error if root package.json cannot be found or verified
+ */
+export declare function findExamplesDirectories(): Promise<string[]>;

package/dist/utils/find-examples-directories.js

@@ -0,0 +1,49 @@
+import { findNearestPackageJson, handleFileNotFoundError, } from '@baseplate-dev/utils/node';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Find all example directories in the Baseplate repository.
+ *
+ * This function locates the root of the Baseplate monorepo by finding the current
+ * package's package.json, then navigating up to find the root package.json with
+ * name "@baseplate-dev/root". It then looks for directories in the examples/ folder.
+ *
+ * @returns Array of absolute paths to example directories
+ * @throws Error if root package.json cannot be found or verified
+ */
+export async function findExamplesDirectories() {
+    // Find current package.json (project-builder-cli)
+    const currentPackageJson = await findNearestPackageJson({
+        cwd: fileURLToPath(import.meta.url),
+    });
+    if (!currentPackageJson) {
+        throw new Error(`Could not find current package.json of @baseplate-dev/project-builder-cli in ${fileURLToPath(import.meta.url)}`);
+    }
+    // Go up one level and find root package.json
+    const parentDir = path.dirname(path.dirname(currentPackageJson));
+    const rootPackageJson = await findNearestPackageJson({
+        cwd: parentDir,
+    });
+    if (!rootPackageJson) {
+        throw new Error(`Could not find root package.json of @baseplate-dev/root in ${parentDir}. Make sure we are running inside the monorepo.`);
+    }
+    // Verify it's the root package
+    const packageContent = await fs.readFile(rootPackageJson, 'utf-8');
+    const packageData = JSON.parse(packageContent);
+    if (packageData.name !== '@baseplate-dev/root') {
+        throw new Error(`Found package.json is not the root package (found: ${packageData.name})`);
+    }
+    // Look for examples directory
+    const rootDir = path.dirname(rootPackageJson);
+    const examplesDir = path.join(rootDir, 'examples');
+    const entries = await fs
+        .readdir(examplesDir, { withFileTypes: true })
+        .catch(handleFileNotFoundError);
+    if (!entries) {
+        throw new Error(`Could not find examples directory in ${examplesDir}. Make sure the examples directory exists.`);
+    }
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(examplesDir, entry.name));
+}

package/dist/utils/list-projects.d.ts

@@ -0,0 +1,58 @@
+import type { ServiceActionProject } from '@baseplate-dev/project-builder-server/actions';
+/**
+ * Lists all available projects by searching through configured directories.
+ *
+ * This function searches for projects in:
+ * - Directories specified in PROJECT_DIRECTORIES environment variable
+ * - Additional directories provided as parameters
+ * - Example directories (if INCLUDE_EXAMPLES is enabled)
+ * - Current working directory (as fallback)
+ *
+ * @param options - Configuration options for project discovery
+ * @param options.additionalDirectories - Optional array of additional directory paths to search for projects
+ * @returns Promise that resolves to an array of discovered projects
+ *
+ * @example
+ * ```typescript
+ * // List all projects from default directories
+ * const projects = await listProjects({});
+ *
+ * // List projects including additional custom directories
+ * const projects = await listProjects({
+ *   additionalDirectories: ['/path/to/custom/projects', '~/my-projects']
+ * });
+ * ```
+ */
+export declare function listProjects({ additionalDirectories, }: {
+    additionalDirectories?: string[];
+}): Promise<ServiceActionProject[]>;
+/**
+ * Resolves a project by name or directory path.
+ *
+ * This function can resolve projects in two ways:
+ * 1. **Path-based resolution**: If the input starts with '.', '/', or '~', it treats the input as a directory path
+ * 2. **Name-based resolution**: Otherwise, it searches through all available projects by name or ID
+ *
+ * @param projectNameOrDirectory - Project name, ID, or directory path to resolve
+ * @returns Promise that resolves to the found project
+ * @throws {Error} When the project cannot be found
+ *
+ * @example
+ * ```typescript
+ * // Resolve by project name
+ * const project = await resolveProject('my-project');
+ *
+ * // Resolve by project ID
+ * const project = await resolveProject('proj_123');
+ *
+ * // Resolve by relative path
+ * const project = await resolveProject('./my-project');
+ *
+ * // Resolve by absolute path
+ * const project = await resolveProject('/path/to/project');
+ *
+ * // Resolve by home directory path
+ * const project = await resolveProject('~/projects/my-project');
+ * ```
+ */
+export declare function resolveProject(projectNameOrDirectory?: string | undefined): Promise<ServiceActionProject>;

package/dist/utils/list-projects.js

@@ -0,0 +1,109 @@
+import { discoverProjects, loadProjectFromDirectory, } from '@baseplate-dev/project-builder-server/actions';
+import path from 'node:path';
+import { logger } from '#src/services/logger.js';
+import { getEnvConfig } from './config.js';
+import { findExamplesDirectories } from './find-examples-directories.js';
+import { expandPathWithTilde } from './path.js';
+const config = getEnvConfig();
+async function getSearchDirectories({ additionalDirectories, includeExamples, defaultToCwd, }) {
+    const allDirectories = new Set();
+    // Add directories from PROJECT_DIRECTORIES env var
+    const envDirectories = config.PROJECT_DIRECTORIES?.split(',') ?? [];
+    for (const dir of envDirectories) {
+        if (dir.trim()) {
+            allDirectories.add(expandPathWithTilde(dir.trim()));
+        }
+    }
+    // Add explicitly provided directories
+    for (const dir of additionalDirectories ?? []) {
+        allDirectories.add(expandPathWithTilde(dir));
+    }
+    // Add example directories if requested
+    if (includeExamples) {
+        const exampleDirs = await findExamplesDirectories();
+        for (const dir of exampleDirs) {
+            allDirectories.add(dir);
+        }
+    }
+    // Default to current working directory if no projects specified
+    if (allDirectories.size === 0 && defaultToCwd) {
+        allDirectories.add(process.cwd());
+    }
+    return [...allDirectories];
+}
+/**
+ * Lists all available projects by searching through configured directories.
+ *
+ * This function searches for projects in:
+ * - Directories specified in PROJECT_DIRECTORIES environment variable
+ * - Additional directories provided as parameters
+ * - Example directories (if INCLUDE_EXAMPLES is enabled)
+ * - Current working directory (as fallback)
+ *
+ * @param options - Configuration options for project discovery
+ * @param options.additionalDirectories - Optional array of additional directory paths to search for projects
+ * @returns Promise that resolves to an array of discovered projects
+ *
+ * @example
+ * ```typescript
+ * // List all projects from default directories
+ * const projects = await listProjects({});
+ *
+ * // List projects including additional custom directories
+ * const projects = await listProjects({
+ *   additionalDirectories: ['/path/to/custom/projects', '~/my-projects']
+ * });
+ * ```
+ */
+export async function listProjects({ additionalDirectories, }) {
+    const searchDirectories = await getSearchDirectories({
+        additionalDirectories,
+        includeExamples: config.INCLUDE_EXAMPLES ?? false,
+        defaultToCwd: true,
+    });
+    return discoverProjects(searchDirectories, logger);
+}
+/**
+ * Resolves a project by name or directory path.
+ *
+ * This function can resolve projects in two ways:
+ * 1. **Path-based resolution**: If the input starts with '.', '/', or '~', it treats the input as a directory path
+ * 2. **Name-based resolution**: Otherwise, it searches through all available projects by name or ID
+ *
+ * @param projectNameOrDirectory - Project name, ID, or directory path to resolve
+ * @returns Promise that resolves to the found project
+ * @throws {Error} When the project cannot be found
+ *
+ * @example
+ * ```typescript
+ * // Resolve by project name
+ * const project = await resolveProject('my-project');
+ *
+ * // Resolve by project ID
+ * const project = await resolveProject('proj_123');
+ *
+ * // Resolve by relative path
+ * const project = await resolveProject('./my-project');
+ *
+ * // Resolve by absolute path
+ * const project = await resolveProject('/path/to/project');
+ *
+ * // Resolve by home directory path
+ * const project = await resolveProject('~/projects/my-project');
+ * ```
+ */
+export async function resolveProject(projectNameOrDirectory = process.cwd()) {
+    if (projectNameOrDirectory.startsWith('.') ||
+        path.isAbsolute(projectNameOrDirectory) ||
+        projectNameOrDirectory.startsWith('~')) {
+        const resolvedPath = expandPathWithTilde(projectNameOrDirectory);
+        const projectInfo = await loadProjectFromDirectory(resolvedPath);
+        return projectInfo;
+    }
+    const projects = await listProjects({});
+    const project = projects.find((p) => p.name === projectNameOrDirectory || p.id === projectNameOrDirectory);
+    if (!project) {
+        throw new Error(`Project ${projectNameOrDirectory} not found`);
+    }
+    return project;
+}

package/dist/utils/project-resolver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Information about a discovered project
+ */
+export interface ProjectInfo {
+    /** Project name from package.json */
+    name: string;
+    /** Absolute path to the project directory */
+    path: string;
+    /** Parsed package.json content */
+    packageJson: Record<string, unknown>;
+    /** Whether this project is from the examples directory */
+    isExample: boolean;
+}
+/**
+ * Options for resolving projects
+ */
+interface ResolveProjectsOptions {
+    /** Whether to include example projects (from INCLUDE_EXAMPLES env) */
+    includeExamples?: boolean;
+    /** Additional directories to include (from PROJECT_DIRECTORIES env or arguments) */
+    directories?: string[];
+    /** Whether to default to current working directory if no projects specified */
+    defaultToCwd?: boolean;
+}
+/**
+ * Resolves all available projects based on the provided options.
+ *
+ * @param options - Configuration for project resolution
+ * @returns Map of project name to ProjectInfo
+ * @throws Error if duplicate project names are found or if project loading fails
+ */
+export declare function resolveProjects(options?: ResolveProjectsOptions): Promise<Map<string, ProjectInfo>>;
+/**
+ * Resolves a single project by name or path.
+ *
+ * @param nameOrPath - Project name or directory path
+ * @returns ProjectInfo for the resolved project
+ * @throws Error if project cannot be resolved or loaded
+ */
+export declare function resolveProject(nameOrPath: string): Promise<ProjectInfo>;
+/**
+ * Gets project directories from resolved projects.
+ *
+ * @param projectMap - Map of resolved projects
+ * @returns Array of absolute directory paths
+ */
+export declare function getProjectDirectories(projectMap: Map<string, ProjectInfo>): string[];
+/**
+ * Gets project names from resolved projects.
+ *
+ * @param projectMap - Map of resolved projects
+ * @returns Array of project names
+ */
+export declare function getProjectNames(projectMap: Map<string, ProjectInfo>): string[];
+export {};

package/dist/utils/project-resolver.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { findExamplesDirectories } from './find-examples-directories.js';
+import { expandPathWithTilde } from './path.js';
+/**
+ * Resolves all available projects based on the provided options.
+ *
+ * @param options - Configuration for project resolution
+ * @returns Map of project name to ProjectInfo
+ * @throws Error if duplicate project names are found or if project loading fails
+ */
+export async function resolveProjects(options = {}) {
+    const { includeExamples = process.env.INCLUDE_EXAMPLES === 'true', directories = [], defaultToCwd = false, } = options;
+    const allDirectories = new Set();
+    // Add directories from PROJECT_DIRECTORIES env var
+    const envDirectories = process.env.PROJECT_DIRECTORIES?.split(',') ?? [];
+    for (const dir of envDirectories) {
+        if (dir.trim()) {
+            allDirectories.add(expandPathWithTilde(dir.trim()));
+        }
+    }
+    // Add explicitly provided directories
+    for (const dir of directories) {
+        allDirectories.add(expandPathWithTilde(dir));
+    }
+    // Add example directories if requested
+    if (includeExamples) {
+        const exampleDirs = await findExamplesDirectories();
+        for (const dir of exampleDirs) {
+            allDirectories.add(dir);
+        }
+    }
+    // Default to current working directory if no projects specified
+    if (allDirectories.size === 0 && defaultToCwd) {
+        allDirectories.add(process.cwd());
+    }
+    const projectMap = new Map();
+    const nameConflicts = [];
+    // Load project info for each directory
+    for (const directory of allDirectories) {
+        try {
+            const projectInfo = await loadProjectInfo(directory);
+            // Check for name conflicts
+            if (projectMap.has(projectInfo.name)) {
+                nameConflicts.push(projectInfo.name);
+            }
+            else {
+                projectMap.set(projectInfo.name, projectInfo);
+            }
+        }
+        catch (error) {
+            console.warn(`Warning: Could not load project from ${directory}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Handle name conflicts
+    if (nameConflicts.length > 0) {
+        throw new Error(`Duplicate project names found: ${nameConflicts.join(', ')}. ` +
+            'Each project must have a unique name in its package.json.');
+    }
+    return projectMap;
+}
+/**
+ * Resolves a single project by name or path.
+ *
+ * @param nameOrPath - Project name or directory path
+ * @returns ProjectInfo for the resolved project
+ * @throws Error if project cannot be resolved or loaded
+ */
+export async function resolveProject(nameOrPath) {
+    // If it looks like a path (contains separators), treat as path
+    if (nameOrPath.includes('/') || nameOrPath.includes('\\')) {
+        const resolvedPath = expandPathWithTilde(nameOrPath);
+        return await loadProjectInfo(resolvedPath);
+    }
+    // Otherwise, try to resolve by name
+    const projectMap = await resolveProjects({
+        includeExamples: process.env.INCLUDE_EXAMPLES === 'true',
+        defaultToCwd: false,
+    });
+    const projectInfo = projectMap.get(nameOrPath);
+    if (!projectInfo) {
+        const availableProjects = [...projectMap.keys()].sort();
+        throw new Error(`Project '${nameOrPath}' not found. Available projects: ${availableProjects.join(', ')}\n` +
+            'You can also specify a directory path directly.');
+    }
+    return projectInfo;
+}
+/**
+ * Loads project information from a directory.
+ *
+ * @param directory - Absolute path to the project directory
+ * @returns ProjectInfo for the project
+ * @throws Error if directory doesn't exist or package.json is invalid
+ */
+async function loadProjectInfo(directory) {
+    const packageJsonPath = path.join(directory, 'package.json');
+    try {
+        const packageJsonContent = await fs.readFile(packageJsonPath, 'utf-8');
+        const packageJson = JSON.parse(packageJsonContent);
+        const name = packageJson.name;
+        if (!name || typeof name !== 'string') {
+            throw new Error('package.json must have a valid "name" field');
+        }
+        // Determine if this is an example project by checking if it's in examples directory
+        const isExample = directory.includes('/examples/') || directory.includes('\\examples\\');
+        return {
+            name,
+            path: directory,
+            packageJson,
+            isExample,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            throw new Error(`No package.json found in ${directory}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Gets project directories from resolved projects.
+ *
+ * @param projectMap - Map of resolved projects
+ * @returns Array of absolute directory paths
+ */
+export function getProjectDirectories(projectMap) {
+    return [...projectMap.values()].map((project) => project.path);
+}
+/**
+ * Gets project names from resolved projects.
+ *
+ * @param projectMap - Map of resolved projects
+ * @returns Array of project names
+ */
+export function getProjectNames(projectMap) {
+    return [...projectMap.keys()].sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baseplate-dev/project-builder-cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Full-stack CLI builder using Baseplate generators",
   "keywords": [
     "cli",
@@ -40,28 +40,29 @@
     "bin/**/*"
   ],
   "dependencies": {
-    "@inquirer/prompts": "7.2.1",
+    "@inquirer/prompts": "7.8.3",
     "commander": "^12.1.0",
     "pino": "9.5.0",
     "pino-pretty": "13.0.0",
     "pkg-dir": "^8.0.0",
-    "zod": "3.24.1",
-    "@baseplate-dev/project-builder-common": "0.3.3",
-    "@baseplate-dev/project-builder-lib": "0.3.3",
-    "@baseplate-dev/project-builder-server": "0.3.3",
-    "@baseplate-dev/project-builder-web": "0.3.3",
-    "@baseplate-dev/utils": "0.3.3"
+    "zod": "3.25.76",
+    "@baseplate-dev/project-builder-common": "0.3.4",
+    "@baseplate-dev/project-builder-lib": "0.3.4",
+    "@baseplate-dev/project-builder-server": "0.3.4",
+    "@baseplate-dev/project-builder-web": "0.3.4",
+    "@baseplate-dev/utils": "0.3.4"
   },
   "devDependencies": {
     "@playwright/test": "1.51.0",
-    "@types/node": "^22.0.0",
+    "@types/node": "^22.17.2",
     "eslint": "9.32.0",
     "fastify": "5.3.2",
+    "memfs": "4.15.1",
     "prettier": "3.6.2",
     "tsx": "4.19.3",
-    "typescript": "5.7.3",
+    "typescript": "5.8.3",
     "vitest": "3.2.4",
-    "@baseplate-dev/tools": "0.3.3"
+    "@baseplate-dev/tools": "0.3.4"
   },
   "engines": {
     "node": "^22.0.0"
@@ -76,13 +77,14 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "clean": "rm -rf ./dist",
-    "dev": "tsx watch --tsconfig ./tsconfig.app.json --exclude /**/node_modules/** --env-file-if-exists=.env -C development ./src/cli.ts",
+    "dev": "tsx watch --tsconfig ./tsconfig.app.json --exclude /**/node_modules/** --env-file-if-exists=../../.env --env-file-if-exists=.env -C development ./src/cli.ts",
+    "dev:dev-server": "pnpm dev dev-server",
     "dev:serve": "pnpm dev serve",
     "lint": "eslint .",
     "prettier:check": "prettier --check .",
     "prettier:write": "prettier -w .",
     "project:generate": "pnpm start generate",
-    "start": "tsx --tsconfig ./tsconfig.app.json --env-file-if-exists=.env -C development ./src/cli.ts",
+    "start": "tsx --tsconfig ./tsconfig.app.json --env-file-if-exists=../../.env --env-file-if-exists=.env -C development ./src/cli.ts",
     "templates:extract": "pnpm start templates extract",
     "templates:generate": "pnpm start templates generate",
     "test": "vitest",