create project with 723 style script (#428)

fixes microsoft/vscode-python-environments#393

Author: eleanorjboyd

src/features/creators/creationHelpers.ts

@@ -96,61 +96,65 @@ export async function quickCreateNewVenv(envManagers: EnvironmentManagers, destF
 }
 
 /**
- * Recursively replaces all occurrences of a string in file and folder names, as well as file contents, within a directory tree.
- * @param dir - The root directory to start the replacement from.
+ * Replaces all occurrences of a string in file and folder names, as well as file contents, within a directory tree or a single file.
+ * @param targetPath - The root directory or file path to start the replacement from.
  * @param searchValue - The string to search for in names and contents.
  * @param replaceValue - The string to replace with.
  * @returns {Promise<void>} Resolves when all replacements are complete.
  */
-export async function replaceInFilesAndNames(dir: string, searchValue: string, replaceValue: string) {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        let entryName = entry.name;
-        let fullPath = path.join(dir, entryName);
-        let newFullPath = fullPath;
-        // If the file or folder name contains searchValue, rename it
-        if (entryName.includes(searchValue)) {
-            const newName = entryName.replace(new RegExp(searchValue, 'g'), replaceValue);
-            newFullPath = path.join(dir, newName);
-            await fs.rename(fullPath, newFullPath);
-            entryName = newName;
-        }
-        if (entry.isDirectory()) {
-            await replaceInFilesAndNames(newFullPath, searchValue, replaceValue);
-        } else {
-            let content = await fs.readFile(newFullPath, 'utf8');
-            if (content.includes(searchValue)) {
-                content = content.replace(new RegExp(searchValue, 'g'), replaceValue);
-                await fs.writeFile(newFullPath, content, 'utf8');
+export async function replaceInFilesAndNames(targetPath: string, searchValue: string, replaceValue: string) {
+    const stat = await fs.stat(targetPath);
+
+    if (stat.isDirectory()) {
+        const entries = await fs.readdir(targetPath, { withFileTypes: true });
+        for (const entry of entries) {
+            let entryName = entry.name;
+            let fullPath = path.join(targetPath, entryName);
+            let newFullPath = fullPath;
+            // If the file or folder name contains searchValue, rename it
+            if (entryName.includes(searchValue)) {
+                const newName = entryName.replace(new RegExp(searchValue, 'g'), replaceValue);
+                newFullPath = path.join(targetPath, newName);
+                await fs.rename(fullPath, newFullPath);
+                entryName = newName;
             }
+            await replaceInFilesAndNames(newFullPath, searchValue, replaceValue);
+        }
+    } else if (stat.isFile()) {
+        let content = await fs.readFile(targetPath, 'utf8');
+        if (content.includes(searchValue)) {
+            content = content.replace(new RegExp(searchValue, 'g'), replaceValue);
+            await fs.writeFile(targetPath, content, 'utf8');
         }
     }
 }
 
 /**
  * Ensures the .github/copilot-instructions.md file exists at the given root, creating or appending as needed.
+ * Performs multiple find-and-replace operations as specified by the replacements array.
  * @param destinationRootPath - The root directory where the .github folder should exist.
- * @param instructionsText - The text to write or append to the copilot-instructions.md file.
+ * @param instructionsFilePath - The path to the instructions template file.
+ * @param replacements - An array of tuples [{ text_to_find_and_replace, text_to_replace_it_with }]
  */
 export async function manageCopilotInstructionsFile(
     destinationRootPath: string,
-    packageName: string,
     instructionsFilePath: string,
+    replacements: Array<{ searchValue: string; replaceValue: string }>,
 ) {
-    const instructionsText = `\n \n` + (await fs.readFile(instructionsFilePath, 'utf-8'));
+    let instructionsText = `\n\n` + (await fs.readFile(instructionsFilePath, 'utf-8'));
+    for (const { searchValue: text_to_find_and_replace, replaceValue: text_to_replace_it_with } of replacements) {
+        instructionsText = instructionsText.replace(new RegExp(text_to_find_and_replace, 'g'), text_to_replace_it_with);
+    }
     const githubFolderPath = path.join(destinationRootPath, '.github');
     const customInstructionsPath = path.join(githubFolderPath, 'copilot-instructions.md');
     if (!(await fs.pathExists(githubFolderPath))) {
-        // make the .github folder if it doesn't exist
         await fs.mkdir(githubFolderPath);
     }
     const customInstructions = await fs.pathExists(customInstructionsPath);
     if (customInstructions) {
-        // Append to the existing file
-        await fs.appendFile(customInstructionsPath, instructionsText.replace(/<package_name>/g, packageName));
+        await fs.appendFile(customInstructionsPath, instructionsText);
     } else {
-        // Create the file if it doesn't exist
-        await fs.writeFile(customInstructionsPath, instructionsText.replace(/<package_name>/g, packageName));
+        await fs.writeFile(customInstructionsPath, instructionsText);
     }
 }
 

src/features/creators/newPackageProject.ts

@@ -140,7 +140,9 @@ export class NewPackageProject implements PythonProjectCreator {
                     'copilot-instructions-text',
                     'package-copilot-instructions.md',
                 );
-                await manageCopilotInstructionsFile(destRoot, packageName, packageInstructionsPath);
+                await manageCopilotInstructionsFile(destRoot, packageInstructionsPath, [
+                    { searchValue: '<package_name>', replaceValue: packageName },
+                ]);
             }
 
             // update launch.json file with config for the package

src/features/creators/newScriptProject.ts

@@ -1,17 +1,118 @@
-import { MarkdownString, window } from 'vscode';
+import * as fs from 'fs-extra';
+import * as path from 'path';
+import { commands, l10n, MarkdownString, QuickInputButtons, Uri, window, workspace } from 'vscode';
 import { PythonProject, PythonProjectCreator, PythonProjectCreatorOptions } from '../../api';
+import { NEW_PROJECT_TEMPLATES_FOLDER } from '../../common/constants';
+import { showInputBoxWithButtons } from '../../common/window.apis';
+import { isCopilotInstalled, manageCopilotInstructionsFile, replaceInFilesAndNames } from './creationHelpers';
 
 export class NewScriptProject implements PythonProjectCreator {
-    public readonly name = 'newScript';
-    public readonly displayName = 'Project';
-    public readonly description = 'Create a new Python project';
-    public readonly tooltip = new MarkdownString('Create a new Python project');
+    public readonly name = l10n.t('newScript');
+    public readonly displayName = l10n.t('Script');
+    public readonly description = l10n.t('Creates a new script folder in your current workspace with PEP 723 support');
+    public readonly tooltip = new MarkdownString(l10n.t('Create a new Python script'));
 
     constructor() {}
 
-    async create(_options?: PythonProjectCreatorOptions): Promise<PythonProject | undefined> {
-        // show notification that the script creation was selected than return undefined
-        window.showInformationMessage('Creating a new Python project...');
+    async create(options?: PythonProjectCreatorOptions): Promise<PythonProject | Uri | undefined> {
+        // quick create (needs name, will always create venv and copilot instructions)
+        // not quick create
+        // ask for script file name
+        // ask if they want venv
+        let scriptFileName = options?.name;
+        let createCopilotInstructions: boolean | undefined;
+        if (options?.quickCreate === true) {
+            // If quickCreate is true, we should not prompt for any input
+            if (!scriptFileName) {
+                throw new Error('Script file name is required in quickCreate mode.');
+            }
+            createCopilotInstructions = true;
+        } else {
+            //Prompt as quickCreate is false
+            if (!scriptFileName) {
+                try {
+                    scriptFileName = await showInputBoxWithButtons({
+                        prompt: l10n.t('What is the name of the script? (e.g. my_script.py)'),
+                        ignoreFocusOut: true,
+                        showBackButton: true,
+                        validateInput: (value) => {
+                            // Ensure the filename ends with .py and follows valid naming conventions
+                            if (!value.endsWith('.py')) {
+                                return l10n.t('Script name must end with ".py".');
+                            }
+                            const baseName = value.replace(/\.py$/, '');
+                            // following PyPI (PEP 508) rules for package names
+                            if (!/^([a-z_]|[a-z0-9_][a-z0-9._-]*[a-z0-9_])$/i.test(baseName)) {
+                                return l10n.t(
+                                    'Invalid script name. Use only letters, numbers, underscores, hyphens, or periods. Must start and end with a letter or number.',
+                                );
+                            }
+                            if (/^[-._0-9]$/i.test(baseName)) {
+                                return l10n.t('Single-character script names cannot be a number, hyphen, or period.');
+                            }
+                            return null;
+                        },
+                    });
+                } catch (ex) {
+                    if (ex === QuickInputButtons.Back) {
+                        await commands.executeCommand('python-envs.createNewProjectFromTemplate');
+                    }
+                }
+                if (!scriptFileName) {
+                    return undefined;
+                }
+                if (isCopilotInstalled()) {
+                    createCopilotInstructions = true;
+                }
+            }
+
+            // 1. Copy template folder
+            const newScriptTemplateFile = path.join(NEW_PROJECT_TEMPLATES_FOLDER, 'new723ScriptTemplate', 'script.py');
+            if (!(await fs.pathExists(newScriptTemplateFile))) {
+                window.showErrorMessage(l10n.t('Template file does not exist, aborting creation.'));
+                return undefined;
+            }
+
+            // Check if the destination folder is provided, otherwise use the first workspace folder
+            let destRoot = options?.rootUri.fsPath;
+            if (!destRoot) {
+                const workspaceFolders = workspace.workspaceFolders;
+                if (!workspaceFolders || workspaceFolders.length === 0) {
+                    window.showErrorMessage(l10n.t('No workspace folder is open or provided, aborting creation.'));
+                    return undefined;
+                }
+                destRoot = workspaceFolders[0].uri.fsPath;
+            }
+
+            // Check if the destination folder already exists
+            const scriptDestination = path.join(destRoot, scriptFileName);
+            if (await fs.pathExists(scriptDestination)) {
+                window.showErrorMessage(
+                    l10n.t(
+                        'A script file by that name already exists, aborting creation. Please retry with a unique script name given your workspace.',
+                    ),
+                );
+                return undefined;
+            }
+            await fs.copy(newScriptTemplateFile, scriptDestination);
+
+            // 2. Replace 'script_name' in the file using a helper (just script name remove .py)
+            await replaceInFilesAndNames(scriptDestination, 'script_name', scriptFileName.replace(/\.py$/, ''));
+
+            // 3. add custom github copilot instructions
+            if (createCopilotInstructions) {
+                const packageInstructionsPath = path.join(
+                    NEW_PROJECT_TEMPLATES_FOLDER,
+                    'copilot-instructions-text',
+                    'script-copilot-instructions.md',
+                );
+                await manageCopilotInstructionsFile(destRoot, packageInstructionsPath, [
+                    { searchValue: '<script_name>', replaceValue: scriptFileName },
+                ]);
+            }
+
+            return Uri.file(scriptDestination);
+        }
         return undefined;
     }
 }

src/features/creators/templates/copilot-instructions-text/script-copilot-instructions.md

@@ -0,0 +1,9 @@
+# Copilot Instructions for <script_name>
+
+-   The script `<script_name>` is a Python python project within the workspace.
+-   It has inline script metadata (as proposed by PEP 723) that defines the script name, required python version, and dependencies.
+-   If imports which require a specific Python version or dependencies are added, keep the inline script metadata up to date.
+-   You need to call the `Get Python Environment Information` tool on the `<script_name>` path to get the Python executable details.
+-   Substitute the Python executable you get from the `Get Python Environment Information` tool anywhere you see `<python>` in these instructions.
+    -   Run command for `<script_name>`: `<python> <script_name>`
+    -   Script can be easily debugged from the Integrated Terminal when activated with the command `debugpy <script_name>` after the necessary environment is activated.

src/features/creators/templates/new723ScriptTemplate/script.py

@@ -0,0 +1,16 @@
+# /// script_name
+# requires-python = ">=X.XX" TODO: Update this to the minimum Python version you want to support
+# dependencies = [
+#   TODO: Add any dependencies your script requires
+# ]
+# ///
+
+# TODO: Update the main function to your needs or remove it.
+
+
+def main() -> None:
+    print("Start coding in Python today!")
+
+
+if __name__ == "__main__":
+    main()