Merge pull request csg-tokyo#84 from maejima-fumika/develop/add-blue-install

Add install command.

Author: chibash

cli/src/commands/create-project.ts

@@ -8,7 +8,8 @@ import { cwd } from "../core/shell";
 import { BOARD_NAMES, isValidBoard } from "../config/board-utils";
 import * as fs from '../core/fs';
 
-const MAIN_TEMPLATE = `print('Hello world!')`;
+const MAIN_FILE_CONTENTS = `print('Hello world!')\n`;
+const GIT_IGNORE_CONTENTS = `**/dist/\n`;
 
 function createProjectDir(projectName: string) {
     const projectDir = path.join(cwd(), projectName);
@@ -21,7 +22,12 @@ function createProjectDir(projectName: string) {
 
 function createMainFile(dir: string) {
     const filePath = path.join(dir, DEFAULT_MAIN_FILE_NAME);
-    fs.writeFile(filePath, MAIN_TEMPLATE);
+    fs.writeFile(filePath, MAIN_FILE_CONTENTS);
+}
+
+function createGitIgnore(dir: string) {
+    const filePath = path.join(dir, '.gitignore');
+    fs.writeFile(filePath, GIT_IGNORE_CONTENTS);
 }
 
 export async function handleCreateProjectCommand(name: string, options: { board?: string }) {
@@ -50,6 +56,7 @@ export async function handleCreateProjectCommand(name: string, options: { board?
         projectConfigHandler.save(projectDir);
 
         createMainFile(projectDir);
+        createGitIgnore(projectDir);
 
         logger.br();
         logger.success(`Success to create a new project.`);

cli/src/commands/install.ts

@@ -0,0 +1,111 @@
+import { Command } from "commander";
+import { logger, showErrorMessages } from "../core/logger";
+import { LOCAL_PACKAGES_DIR, ProjectConfigHandler, PackageSource } from "../config/project-config";
+import { GLOBAL_BLUESCRIPT_PATH } from "../config/global-config";
+import { cwd, exec } from "../core/shell";
+import * as fs from '../core/fs';
+import * as path from 'path';
+
+
+class InstallationHandler {
+    private projectConfigHandler: ProjectConfigHandler;
+    private projectRootDir: string;
+    private packagesDir: string;
+
+    constructor() {
+        this.projectRootDir = cwd();
+        this.projectConfigHandler = ProjectConfigHandler.load(this.projectRootDir);
+        this.packagesDir = LOCAL_PACKAGES_DIR(this.projectRootDir);
+    }
+
+    public async installAll() {
+        this.ensurePackageDir();
+        await this.processInstallQueue(this.projectConfigHandler.getDepenencies());
+    }
+
+    public async installPackage(url: string, version?: string) {
+        this.ensurePackageDir();
+        const packageConfigHandler = await this.downloadPackage(url, version);
+        const packageName = packageConfigHandler.getConfig().projectName;
+        await this.processInstallQueue(packageConfigHandler.getDepenencies());
+        this.projectConfigHandler.addDependency({name: packageName, url, version});
+        this.projectConfigHandler.save(this.projectRootDir);
+    }
+
+    private async processInstallQueue(queue: PackageSource[]) {
+        const installedPackages = new Set<string>();
+
+        while (queue.length > 0) {
+            const currentPkg = queue.shift();
+            if (!currentPkg) break;
+            if (installedPackages.has(currentPkg.name)) continue;
+
+            const pkgConfigHandler = await this.downloadPackage(currentPkg.url, currentPkg.version);
+            pkgConfigHandler.checkVmVersion(this.projectConfigHandler.getConfig().vmVersion);
+            installedPackages.add(currentPkg.name);
+            pkgConfigHandler.getDepenencies().forEach((pkgDep) => {
+                installedPackages.add(pkgDep.name);
+            });        
+        }
+    }
+
+    private ensurePackageDir() {
+        if (!fs.exists(this.packagesDir)) {
+            fs.makeDir(this.packagesDir);
+        }
+    }
+
+    private async downloadPackage(url: string, version?: string): Promise<ProjectConfigHandler> {
+        logger.log(`Downloading from ${url}...`);
+        const tmpDir = path.join(GLOBAL_BLUESCRIPT_PATH, 'tmp-package');
+        const branchCmd = version ? `--branch ${version}` : '';
+        const cmd = `git clone --depth 1 ${branchCmd} ${url} ${tmpDir}`;
+        try {
+            await exec(cmd, {silent: true});
+            const gitDir = path.join(tmpDir, '.git');
+            if (fs.exists(gitDir)) {
+                fs.removeDir(gitDir);
+            }
+            const configHandler = ProjectConfigHandler.load(tmpDir);
+            const packageName = configHandler.getConfig().projectName;
+            const packageDir = path.join(this.packagesDir, packageName);
+            if (fs.exists(packageDir)) {
+                fs.removeDir(packageDir);
+            }
+            fs.moveDir(tmpDir, packageDir);
+            return configHandler;
+        } catch (error) {
+            if (fs.exists(tmpDir)) {
+                fs.removeDir(tmpDir);
+            }
+            throw new Error(`Failed to download package from '${url}'.`, {cause: error});
+        }
+  }
+}
+
+
+export async function handleInstallCommand(url: string|undefined, options: {tag?: string}) {
+    try {
+        const installationHandler = new InstallationHandler();
+        if (url) {
+            installationHandler.installPackage(url, options.tag);
+        } else {
+            installationHandler.installAll();
+        }
+    } catch (error) {
+        const errorMessage = 
+            url ? `Failed to install ${url}.` : `Failed to install packages.`;
+        logger.error(errorMessage);
+        showErrorMessages(error);
+        process.exit(1);
+    }
+}
+
+export function registerInstallCommand(program: Command) {
+    program
+        .command('install')
+        .description('install all dependencies, or add a new package via Git URL')
+        .argument('[git-url]', 'git repository URL to add as a dependency')
+        .option('-t, --tag <tag>', 'git tag or branch to checkout (e.g., v1.0.0)')
+        .action(handleInstallCommand);
+}

cli/src/commands/repl.ts

@@ -194,7 +194,7 @@ class ESP32ReplHandler extends ReplHandler {
             return {
                 name: packageName,
                 espIdfComponents: projectConfigHandler.espIdfComponents,
-                dependencies: projectConfigHandler.dependencies,
+                dependencies: Object.keys(projectConfigHandler.dependencies),
                 dirs: {
                     root,
                     dist: DIST_DIR(root),

cli/src/commands/run.ts

@@ -173,7 +173,7 @@ class ESP32RunHandler extends RunHandler {
             return {
                 name: packageName,
                 espIdfComponents: projectConfigHandler.espIdfComponents,
-                dependencies: projectConfigHandler.dependencies,
+                dependencies: Object.keys(projectConfigHandler.dependencies),
                 dirs: {
                     root,
                     dist: DIST_DIR(root),

cli/src/commands/uninstall.ts

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+import { logger, showErrorMessages } from "../core/logger";
+import { LOCAL_PACKAGES_DIR, ProjectConfigHandler } from "../config/project-config";
+import { cwd } from "../core/shell";
+import * as fs from '../core/fs';
+import * as path from 'path';
+
+
+export async function handleUninstallCommand(packageName: string) {
+    try {
+        const projectRootDir = cwd();
+        const projectConfigHandler = ProjectConfigHandler.load(projectRootDir);
+        const packageDir = path.join(LOCAL_PACKAGES_DIR(projectRootDir), packageName);
+        if (!projectConfigHandler.dependencyExists(packageName)) {
+            throw new Error(`Package ${packageName} is not listed in bsconfig.json dependencies.`)
+        }
+        if (fs.exists(packageDir)) {
+            fs.removeDir(packageDir);
+        }
+        projectConfigHandler.removeDepedency(packageName);
+        projectConfigHandler.save(projectRootDir);
+    } catch (error) {
+        logger.error(`Failed to uninstall ${packageName}.`);
+        showErrorMessages(error);
+        process.exit(1);
+    }
+}
+
+export function registerUninstallCommand(program: Command) {
+    program
+        .command('uninstall')
+        .description('uninstall a package')
+        .argument('<package-name>', 'Package name')
+        .action(handleUninstallCommand);
+}

cli/src/config/project-config.ts

@@ -20,7 +20,7 @@ const baseConfigSchema = z.object({
     version: z.string().default(DEfAULT_PROJECT_VERSION),
     vmVersion: z.string().default(VM_VERSION),
     deviceName: z.string().default(DEFAULT_DEVICE_NAME).optional(),
-    dependencies: z.array(z.string()).default([]),
+    dependencies: z.record(z.string(), z.string()).default({}),
     runtimeDir: z.string().optional(), // for dev
     globalPackagesDir: z.string().optional(), // for dev
 });
@@ -38,6 +38,12 @@ export type ProjectConfig = z.infer<typeof projectConfigSchema>;
 
 export type SpecificBoardConfig<B extends BoardName> = Extract<ProjectConfig, { boardName: B }>;
 
+export type PackageSource = {
+    name: string,
+    url: string,
+    version?: string
+};
+
 export class ProjectConfigHandler {
     private config: ProjectConfig;
 
@@ -85,6 +91,12 @@ export class ProjectConfigHandler {
         return this.config;
     }
 
+    public checkVmVersion(expected: string) {
+        if (expected !== this.config.vmVersion) {
+            throw new Error(`VM version of ${this.config.projectName} is not match the expected VM version(${expected}).`);
+        }
+    }
+
     public getBoardName(): BoardName {
         return this.config.boardName;
     }
@@ -101,8 +113,8 @@ export class ProjectConfigHandler {
     public update(config: Partial<ProjectConfig>) {
         try {
             this.config = projectConfigSchema.parse({
-                ...config,
-                ...this.config
+                ...this.config,
+                ...config
             });
         } catch (error) {
             if (error instanceof z.ZodError) {
@@ -112,10 +124,36 @@ export class ProjectConfigHandler {
         }
     }
 
-    public addDependency(dependency: string) {
-        const newDependencies = [...new Set([...this.config.dependencies, dependency])];
-        this.update({
-            dependencies: newDependencies
+    public addDependency(source: PackageSource) {
+        const newDependencies = {...this.config.dependencies}
+        newDependencies[source.name] = 
+                source.version ? `${source.url}#${source.version}` : source.url;
+        this.update({dependencies: newDependencies});
+    }
+
+    public removeDepedency(name: string) {
+        const newDependencies = {...this.config.dependencies};
+        delete newDependencies[name];
+        this.update({dependencies: newDependencies});
+    }
+
+    public dependencyExists(name: string) {
+        return Object.keys(this.config.dependencies).includes(name);
+    }
+
+    public getDepenencies(): PackageSource[] {
+        return Object.keys(this.config.dependencies).map(name => {
+            const depString = this.config.dependencies[name];
+            let url = depString;
+            let version: string | undefined = undefined;
+
+            // #extract tag (git-url#commit-ish)
+            if (depString.includes('#')) {
+                const parts = depString.split('#');
+                url = parts[0];
+                version = parts[1];
+            }
+            return {name, url, version};
         });
     }
 

cli/src/core/fs.ts

@@ -11,6 +11,10 @@ export function removeDir(path: string) {
     fs.rmSync(path, { recursive: true });
 }
 
+export function moveDir(from: string, to: string) {
+    fs.renameSync(from, to);
+}
+
 export function exists(path: string): boolean {
     return fs.existsSync(path);
 }

cli/src/index.ts

@@ -13,6 +13,8 @@ import { registerCreateProjectCommand } from './commands/create-project';
 import { registerRunCommand } from './commands/run';
 import { registerFullcleanCommand } from './commands/board/full-clean';
 import { registerReplCommand } from './commands/repl';
+import { registerInstallCommand } from './commands/install';
+import { registerUninstallCommand } from './commands/uninstall';
 
 
 function registerBoardCommands(program: Command) {
@@ -42,6 +44,8 @@ function main() {
     registerCreateProjectCommand(command);
     registerRunCommand(command);
     registerReplCommand(command);
+    registerInstallCommand(command);
+    registerUninstallCommand(command);
 
     command.parse(process.argv);
 }

cli/tests/commands/mock-helpers.ts

@@ -45,6 +45,10 @@ export function setupMocks() {
       update: jest.fn(),
       updateWithDependency: jest.fn(),
       save: jest.fn(),
+      addDependency: jest.fn(),
+      removeDepedency: jest.fn(),
+      dependencyExists: jest.fn(),
+      getDepenencies: jest.fn()
   };
   jest.spyOn(ProjectConfigHandler, 'createTemplate').mockReturnValue(mockProjectConfigHandler as unknown as ProjectConfigHandler);
   jest.spyOn(ProjectConfigHandler, 'load').mockReturnValue(mockProjectConfigHandler as unknown as ProjectConfigHandler);

website/docs/reference/cli.md

@@ -8,7 +8,7 @@ The BlueScript CLI (`blue`) is the primary tool for managing projects, setting u
 npm install -g @bluescript/cli
 ```
 
-## Project Commands
+## Core Commands
 
 ### `blue create-project`
 
@@ -42,6 +42,50 @@ blue create-project my-app --board esp32
 
 ---
 
+### `blue install`
+
+Installs project dependencies. This command has two modes:
+
+1. **Install All:** If run without arguments, it installs all dependencies listed in bsconfig.json.
+2. **Add Package:** If a Git URL is provided, it downloads the package, adds it to bsconfig.json, and installs it.
+
+```bash
+blue install [git-url] [options]
+```
+
+**Arguments:**
+*   `<git-url>`: (Optional) The URL of the Git repository to add as a dependency.
+
+**Options:**
+
+| Option | Alias | Description |
+| :--- | :--- | :--- |
+| `--tag` | `-t` | Specify a git tag or branch to checkout (e.g., `v1.0.0`, `main`). |
+
+**Example:**
+```bash
+# Restore all dependencies from bsconfig.json
+blue install
+
+# Install a specific library (e.g., GPIO library)
+blue install https://github.com/bluescript/gpio.git
+
+# Install a specific version of a library
+blue install https://github.com/bluescript/drivers.git --tag v2.0.0
+```
+
+---
+
+### `blue uninstall`
+
+Uninstall the specified package from the current project.
+
+```bash
+blue install [package-name]
+```
+
+---
+
 ### `blue run`
 
 Compiles the current project and executes it on a target device via Bluetooth.