@tanstack/cta-cli 0.10.0-alpha.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -0,0 +1,149 @@
+import { Command, InvalidArgumentError } from 'commander';
+import { intro, log } from '@clack/prompts';
+import chalk from 'chalk';
+import { SUPPORTED_PACKAGE_MANAGERS, addToApp, createApp, getAllAddOns, getFrameworkById, getFrameworkByName, getFrameworks, } from '@tanstack/cta-engine';
+import { initAddOn } from '@tanstack/cta-custom-add-on';
+import { runMCPServer } from '@tanstack/cta-mcp';
+import { launchUI } from '@tanstack/cta-ui';
+import { normalizeOptions, promptForOptions } from './options.js';
+import { createUIEnvironment } from './ui-environment.js';
+async function listAddOns(options, { forcedMode, forcedAddOns = [], }) {
+    const addOns = await getAllAddOns(getFrameworkById(options.framework || 'react-cra'), forcedMode || options.template || 'typescript');
+    for (const addOn of addOns.filter((a) => !forcedAddOns.includes(a.id))) {
+        console.log(`${chalk.bold(addOn.id)}: ${addOn.description}`);
+    }
+}
+export function cli({ name, appName, forcedMode, forcedAddOns, }) {
+    const environment = createUIEnvironment();
+    const program = new Command();
+    const availableFrameworks = getFrameworks().map((f) => f.name);
+    const toolchains = new Set();
+    for (const framework of getFrameworks()) {
+        for (const addOn of framework.getAddOns()) {
+            if (addOn.type === 'toolchain') {
+                toolchains.add(addOn.id);
+            }
+        }
+    }
+    program.name(name).description(`CLI to create a new ${appName} application`);
+    program
+        .command('add')
+        .argument('add-on', 'Name of the add-on (or add-ons separated by commas)')
+        .action(async (addOn) => {
+        await addToApp(addOn.split(',').map((addon) => addon.trim()), {
+            silent: false,
+        }, environment);
+    });
+    const addOnCommand = program.command('add-on');
+    addOnCommand
+        .command('update')
+        .description('Create or update an add-on from the current project')
+        .action(async () => {
+        await initAddOn('add-on', environment);
+    });
+    addOnCommand
+        .command('ui')
+        .description('Show the add-on developer UI')
+        .action(async () => {
+        launchUI();
+    });
+    program
+        .command('update-starter')
+        .description('Create or update a project starter from the current project')
+        .action(async () => {
+        await initAddOn('starter', environment);
+    });
+    program.argument('[project-name]', 'name of the project');
+    if (!forcedMode) {
+        program.option('--template <type>', 'project template (typescript, javascript, file-router)', (value) => {
+            if (value !== 'typescript' &&
+                value !== 'javascript' &&
+                value !== 'file-router') {
+                throw new InvalidArgumentError(`Invalid template: ${value}. Only the following are allowed: typescript, javascript, file-router`);
+            }
+            return value;
+        });
+    }
+    program
+        .option('--framework <type>', `project framework (${availableFrameworks.join(', ')})`, (value) => {
+        if (!availableFrameworks.includes(value)) {
+            throw new InvalidArgumentError(`Invalid framework: ${value}. Only the following are allowed: ${availableFrameworks.join(', ')}`);
+        }
+        return value;
+    }, 'react')
+        .option('--starter [url]', 'initialize this project from a starter URL', false)
+        .option(`--package-manager <${SUPPORTED_PACKAGE_MANAGERS.join('|')}>`, `Explicitly tell the CLI to use this package manager`, (value) => {
+        if (!SUPPORTED_PACKAGE_MANAGERS.includes(value)) {
+            throw new InvalidArgumentError(`Invalid package manager: ${value}. The following are allowed: ${SUPPORTED_PACKAGE_MANAGERS.join(', ')}`);
+        }
+        return value;
+    })
+        .option(`--toolchain <${Array.from(toolchains).join('|')}>`, `Explicitly tell the CLI to use this toolchain`, (value) => {
+        if (!toolchains.has(value)) {
+            throw new InvalidArgumentError(`Invalid toolchain: ${value}. The following are allowed: ${Array.from(toolchains).join(', ')}`);
+        }
+        return value;
+    })
+        .option('--tailwind', 'add Tailwind CSS', false)
+        .option('--add-ons [...add-ons]', 'pick from a list of available add-ons (comma separated list)', (value) => {
+        let addOns = !!value;
+        if (typeof value === 'string') {
+            addOns = value.split(',').map((addon) => addon.trim());
+        }
+        return addOns;
+    })
+        .option('--list-add-ons', 'list all available add-ons', false)
+        .option('--no-git', 'do not create a git repository')
+        .option('--target-dir <path>', 'the target directory for the application root')
+        .option('--mcp', 'run the MCP server', false)
+        .option('--mcp-sse', 'run the MCP server in SSE mode', false);
+    program.action(async (projectName, options) => {
+        if (options.listAddOns) {
+            await listAddOns(options, {
+                forcedMode: forcedMode,
+                forcedAddOns,
+            });
+        }
+        else if (options.mcp || options.mcpSse) {
+            await runMCPServer(!!options.mcpSse, {
+                forcedMode: forcedMode,
+                forcedAddOns,
+                appName,
+            });
+        }
+        else {
+            try {
+                const cliOptions = {
+                    projectName,
+                    ...options,
+                };
+                cliOptions.framework = getFrameworkByName(options.framework || 'react').id;
+                if (forcedMode) {
+                    cliOptions.template = forcedMode;
+                }
+                let finalOptions = await normalizeOptions(cliOptions, forcedMode, forcedAddOns);
+                if (finalOptions) {
+                    intro(`Creating a new ${appName} app in ${projectName}...`);
+                }
+                else {
+                    intro(`Let's configure your ${appName} application`);
+                    finalOptions = await promptForOptions(cliOptions, {
+                        forcedMode: forcedMode,
+                        forcedAddOns,
+                    });
+                }
+                await createApp(finalOptions, {
+                    environment: createUIEnvironment(),
+                    cwd: options.targetDir || undefined,
+                    name,
+                    appName,
+                });
+            }
+            catch (error) {
+                log.error(error instanceof Error ? error.message : 'An unknown error occurred');
+                process.exit(1);
+            }
+        }
+    });
+    program.parse();
+}

package/dist/index.js

@@ -0,0 +1 @@
+export { cli } from './cli.js';

package/dist/options.js

@@ -0,0 +1,358 @@
+import { cancel, confirm, isCancel, multiselect, select, text, } from '@clack/prompts';
+import { CODE_ROUTER, DEFAULT_PACKAGE_MANAGER, FILE_ROUTER, SUPPORTED_PACKAGE_MANAGERS, finalizeAddOns, getAllAddOns, getFrameworkById, getPackageManager, loadRemoteAddOn, } from '@tanstack/cta-engine';
+// If all CLI options are provided, use them directly
+export async function normalizeOptions(cliOptions, forcedMode, forcedAddOns) {
+    // in some cases, if you use windows/powershell, the argument for addons
+    // if sepparated by comma is not really passed as an array, but as a string
+    // with spaces, We need to normalize this edge case.
+    if (Array.isArray(cliOptions.addOns) && cliOptions.addOns.length === 1) {
+        const parseSeparatedArgs = cliOptions.addOns[0].split(' ');
+        if (parseSeparatedArgs.length > 1) {
+            cliOptions.addOns = parseSeparatedArgs;
+        }
+    }
+    if (cliOptions.projectName) {
+        let typescript = cliOptions.template === 'typescript' ||
+            cliOptions.template === 'file-router' ||
+            cliOptions.framework === 'solid';
+        let tailwind = !!cliOptions.tailwind;
+        if (cliOptions.framework === 'solid') {
+            tailwind = true;
+        }
+        let mode = cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER;
+        const starter = cliOptions.starter
+            ? (await loadRemoteAddOn(cliOptions.starter))
+            : undefined;
+        if (starter) {
+            tailwind = starter.tailwind;
+            typescript = starter.typescript;
+            cliOptions.framework = starter.framework;
+            mode = starter.mode;
+        }
+        let addOns = false;
+        let chosenAddOns = [];
+        if (Array.isArray(cliOptions.addOns) ||
+            starter?.dependsOn ||
+            forcedAddOns ||
+            cliOptions.toolchain) {
+            addOns = true;
+            let finalAddOns = Array.from(new Set([...(starter?.dependsOn || []), ...(forcedAddOns || [])]));
+            if (cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
+                finalAddOns = Array.from(new Set([
+                    ...(forcedAddOns || []),
+                    ...finalAddOns,
+                    ...cliOptions.addOns,
+                ]));
+            }
+            const framework = getFrameworkById(cliOptions.framework || 'react-cra');
+            if (cliOptions.toolchain) {
+                finalAddOns.push(cliOptions.toolchain);
+            }
+            chosenAddOns = await finalizeAddOns(framework, forcedMode || cliOptions.template === 'file-router'
+                ? FILE_ROUTER
+                : CODE_ROUTER, finalAddOns);
+            tailwind = true;
+            typescript = true;
+        }
+        return {
+            // TODO: This is a bit to fix the default framework
+            framework: getFrameworkById(cliOptions.framework || 'react-cra'),
+            projectName: cliOptions.projectName,
+            typescript,
+            tailwind,
+            packageManager: cliOptions.packageManager ||
+                getPackageManager() ||
+                DEFAULT_PACKAGE_MANAGER,
+            mode,
+            git: !!cliOptions.git,
+            addOns,
+            chosenAddOns,
+            variableValues: {},
+            starter,
+        };
+    }
+}
+async function collectVariables(variables) {
+    const responses = {};
+    for (const variable of variables) {
+        if (variable.type === 'string') {
+            const response = await text({
+                message: variable.description,
+                initialValue: variable.default,
+            });
+            if (isCancel(response)) {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+            responses[variable.name] = response;
+        }
+        else if (variable.type === 'number') {
+            const response = await text({
+                message: variable.description,
+                initialValue: variable.default.toString(),
+            });
+            if (isCancel(response)) {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+            responses[variable.name] = Number(response);
+        }
+        else {
+            const response = await confirm({
+                message: variable.description,
+                initialValue: variable.default === true,
+            });
+            if (isCancel(response)) {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+            responses[variable.name] = response;
+        }
+    }
+    return responses;
+}
+export async function promptForOptions(cliOptions, { forcedAddOns = [], forcedMode, }) {
+    const options = {};
+    const framework = getFrameworkById(cliOptions.framework || 'react-cra');
+    options.framework = framework;
+    // TODO: This is a bit of a hack to ensure that the framework is solid
+    if (options.framework.id === 'solid') {
+        options.typescript = true;
+        options.tailwind = true;
+    }
+    if (cliOptions.addOns) {
+        options.typescript = true;
+    }
+    if (!cliOptions.projectName) {
+        const value = await text({
+            message: 'What would you like to name your project?',
+            defaultValue: 'my-app',
+            validate(value) {
+                if (!value) {
+                    return 'Please enter a name';
+                }
+            },
+        });
+        if (isCancel(value)) {
+            cancel('Operation cancelled.');
+            process.exit(0);
+        }
+        options.projectName = value;
+    }
+    // Router type selection
+    if (!cliOptions.template && !forcedMode) {
+        const routerType = await select({
+            message: 'Select the router type:',
+            options: [
+                {
+                    value: FILE_ROUTER,
+                    label: 'File Router - File-based routing structure',
+                },
+                {
+                    value: CODE_ROUTER,
+                    label: 'Code Router - Traditional code-based routing',
+                },
+            ],
+            initialValue: FILE_ROUTER,
+        });
+        if (isCancel(routerType)) {
+            cancel('Operation cancelled.');
+            process.exit(0);
+        }
+        options.mode = routerType;
+    }
+    else if (forcedMode) {
+        options.mode = forcedMode === 'file-router' ? FILE_ROUTER : CODE_ROUTER;
+        options.typescript = options.mode === FILE_ROUTER;
+    }
+    else {
+        options.mode =
+            cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER;
+        if (options.mode === FILE_ROUTER) {
+            options.typescript = true;
+        }
+    }
+    // TypeScript selection (if using Code Router)
+    if (!options.typescript) {
+        if (options.mode === CODE_ROUTER) {
+            const typescriptEnable = await confirm({
+                message: 'Would you like to use TypeScript?',
+                initialValue: true,
+            });
+            if (isCancel(typescriptEnable)) {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+            options.typescript = typescriptEnable;
+        }
+        else {
+            options.typescript = true;
+        }
+    }
+    // Tailwind selection
+    if (!cliOptions.tailwind && options.framework.id === 'react-cra') {
+        const tailwind = await confirm({
+            message: 'Would you like to use Tailwind CSS?',
+            initialValue: true,
+        });
+        if (isCancel(tailwind)) {
+            cancel('Operation cancelled.');
+            process.exit(0);
+        }
+        options.tailwind = tailwind;
+    }
+    else {
+        // TODO: This is a bit of a hack to ensure that the framework is solid
+        options.tailwind = options.framework.id === 'solid' || !!cliOptions.tailwind;
+    }
+    // Package manager selection
+    if (cliOptions.packageManager === undefined) {
+        const detectedPackageManager = getPackageManager();
+        if (!detectedPackageManager) {
+            const pm = await select({
+                message: 'Select package manager:',
+                options: SUPPORTED_PACKAGE_MANAGERS.map((pm) => ({
+                    value: pm,
+                    label: pm,
+                })),
+                initialValue: DEFAULT_PACKAGE_MANAGER,
+            });
+            if (isCancel(pm)) {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+            options.packageManager = pm;
+        }
+        else {
+            options.packageManager = detectedPackageManager;
+        }
+    }
+    else {
+        options.packageManager = cliOptions.packageManager;
+    }
+    // Toolchain selection
+    let toolchain = undefined;
+    if (cliOptions.toolchain === undefined) {
+        const toolchains = new Set();
+        for (const addOn of framework.getAddOns()) {
+            if (addOn.type === 'toolchain') {
+                toolchains.add(addOn);
+            }
+        }
+        const tc = await select({
+            message: 'Select toolchain',
+            options: [
+                {
+                    value: undefined,
+                    label: 'None',
+                },
+                ...Array.from(toolchains).map((tc) => ({
+                    value: tc,
+                    label: tc.name,
+                })),
+            ],
+            initialValue: undefined,
+        });
+        if (isCancel(tc)) {
+            cancel('Operation cancelled.');
+            process.exit(0);
+        }
+        toolchain = tc;
+    }
+    else {
+        for (const addOn of framework.getAddOns()) {
+            if (addOn.type === 'toolchain' && addOn.id === cliOptions.toolchain) {
+                toolchain = addOn;
+            }
+        }
+    }
+    options.chosenAddOns = toolchain ? [toolchain] : [];
+    if (Array.isArray(cliOptions.addOns)) {
+        options.chosenAddOns = await finalizeAddOns(options.framework, options.mode, Array.from(new Set([...cliOptions.addOns, ...forcedAddOns, toolchain?.id])).filter(Boolean));
+        options.tailwind = true;
+    }
+    else if (cliOptions.addOns) {
+        // Select any add-ons
+        const allAddOns = await getAllAddOns(options.framework, options.mode);
+        const addOns = allAddOns.filter((addOn) => addOn.type === 'add-on');
+        let selectedAddOns = [];
+        if (options.typescript && addOns.length > 0) {
+            const value = await multiselect({
+                message: 'What add-ons would you like for your project:',
+                options: addOns
+                    .filter((addOn) => !forcedAddOns.includes(addOn.id))
+                    .map((addOn) => ({
+                    value: addOn.id,
+                    label: addOn.name,
+                    hint: addOn.description,
+                })),
+                required: false,
+            });
+            if (isCancel(value)) {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+            selectedAddOns = value;
+        }
+        // Select any examples
+        let selectedExamples = [];
+        const examples = allAddOns.filter((addOn) => addOn.type === 'example');
+        if (options.typescript && examples.length > 0) {
+            const value = await multiselect({
+                message: 'Would you like any examples?',
+                options: examples
+                    .filter((addOn) => !forcedAddOns.includes(addOn.id))
+                    .map((addOn) => ({
+                    value: addOn.id,
+                    label: addOn.name,
+                    hint: addOn.description,
+                })),
+                required: false,
+            });
+            if (isCancel(value)) {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+            selectedExamples = value;
+        }
+        if (selectedAddOns.length > 0 ||
+            selectedExamples.length > 0 ||
+            forcedAddOns.length > 0 ||
+            toolchain) {
+            options.chosenAddOns = await finalizeAddOns(options.framework, options.mode, Array.from(new Set([
+                ...selectedAddOns,
+                ...selectedExamples,
+                ...forcedAddOns,
+                toolchain?.id,
+            ])).filter(Boolean));
+            options.tailwind = true;
+        }
+    }
+    else if (forcedAddOns.length > 0) {
+        options.chosenAddOns = await finalizeAddOns(options.framework, options.mode, Array.from(new Set([...forcedAddOns, toolchain?.id])).filter(Boolean));
+    }
+    // Collect variables
+    const variables = [];
+    for (const addOn of options.chosenAddOns) {
+        for (const variable of addOn.variables ?? []) {
+            variables.push(variable);
+        }
+    }
+    options.variableValues = await collectVariables(variables);
+    // Git selection
+    if (cliOptions.git === undefined) {
+        const git = await confirm({
+            message: 'Would you like to initialize a new git repository?',
+            initialValue: true,
+        });
+        if (isCancel(git)) {
+            cancel('Operation cancelled.');
+            process.exit(0);
+        }
+        options.git = git;
+    }
+    else {
+        options.git = !!cliOptions.git;
+    }
+    return options;
+}

package/dist/types/cli.d.ts

@@ -0,0 +1,7 @@
+import type { Mode } from '@tanstack/cta-engine';
+export declare function cli({ name, appName, forcedMode, forcedAddOns, }: {
+    name: string;
+    appName: string;
+    forcedMode?: Mode;
+    forcedAddOns?: Array<string>;
+}): void;

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export { cli } from './cli.js';

package/dist/types/options.d.ts

@@ -0,0 +1,7 @@
+import type { Mode, Options, TemplateOptions } from '@tanstack/cta-engine';
+import type { CliOptions } from './types.js';
+export declare function normalizeOptions(cliOptions: CliOptions, forcedMode?: Mode, forcedAddOns?: Array<string>): Promise<Options | undefined>;
+export declare function promptForOptions(cliOptions: CliOptions, { forcedAddOns, forcedMode, }: {
+    forcedAddOns?: Array<string>;
+    forcedMode?: TemplateOptions;
+}): Promise<Required<Options>>;

package/dist/types/types.d.ts

@@ -0,0 +1,16 @@
+import type { PackageManager, TemplateOptions } from '@tanstack/cta-engine';
+export interface CliOptions {
+    template?: TemplateOptions;
+    framework?: string;
+    tailwind?: boolean;
+    packageManager?: PackageManager;
+    toolchain?: string;
+    projectName?: string;
+    git?: boolean;
+    addOns?: Array<string> | boolean;
+    listAddOns?: boolean;
+    mcp?: boolean;
+    mcpSse?: boolean;
+    starter?: string;
+    targetDir?: string;
+}

package/dist/types/ui-environment.d.ts

@@ -0,0 +1,2 @@
+import type { Environment } from '@tanstack/cta-engine';
+export declare function createUIEnvironment(): Environment;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui-environment.js

@@ -0,0 +1,49 @@
+import { cancel, confirm, intro, isCancel, log, outro, spinner, } from '@clack/prompts';
+import chalk from 'chalk';
+import { createDefaultEnvironment } from '@tanstack/cta-engine';
+export function createUIEnvironment() {
+    const defaultEnvironment = createDefaultEnvironment();
+    return {
+        ...defaultEnvironment,
+        intro: (message) => {
+            intro(message);
+        },
+        outro: (message) => {
+            outro(message);
+        },
+        info: (title, message) => {
+            console.log('info', title, message);
+            log.info(`${title ? chalk.red(title) : ''}${message ? chalk.green(message) : ''}`);
+        },
+        error: (title, message) => {
+            console.log('error', title, message);
+            log.error(`${title ? `${title}: ` : ''}${message}`);
+        },
+        warn: (title, message) => {
+            console.log('warn', title, message);
+            log.warn(`${title ? `${title}: ` : ''}${message}`);
+        },
+        confirm: async (message) => {
+            console.log('confirm', message);
+            const shouldContinue = await confirm({
+                message,
+            });
+            if (isCancel(shouldContinue)) {
+                cancel('Operation cancelled.');
+                process.exit(0);
+            }
+            return shouldContinue;
+        },
+        spinner: () => {
+            const s = spinner();
+            return {
+                start: (message) => {
+                    s.start(message);
+                },
+                stop: (message) => {
+                    s.stop(message);
+                },
+            };
+        },
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tanstack/cta-cli",
+  "version": "0.10.0-alpha.16",
+  "description": "Tanstack Application Builder CLI",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TanStack/create-tsrouter-app.git"
+  },
+  "homepage": "https://tanstack.com/router",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "react",
+    "tanstack",
+    "router",
+    "create-react-app"
+  ],
+  "author": "Jack Herrington <jherr@pobox.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "@tanstack/cta-engine": "0.10.0-alpha.16",
+    "@tanstack/cta-mcp": "0.10.0-alpha.16",
+    "@tanstack/cta-ui": "0.10.0-alpha.16",
+    "@tanstack/cta-custom-add-on": "0.10.0-alpha.16"
+  },
+  "devDependencies": {
+    "@tanstack/config": "^0.16.2",
+    "@types/node": "^22.13.4",
+    "eslint": "^9.20.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.0.8"
+  },
+  "scripts": {}
+}