feat: add project write path security guard, macOS SDK auto-detection, and walkthrough improvements

CONTRIBUTING.md

@@ -32,7 +32,22 @@ git submodule update --init --recursive
 pnpm install
 ```
 
-使用`vscode`打开文件夹打开项目根目录，点击键盘上的`F5`即可启动一个扩展开发宿主进程，打开另一个`vscode`窗口，开始调试项目。
+> **💡 关于依赖安装:**
+>
+> 本项目使用 pnpm workspace + `nodeLinker: isolated`（严格隔离模式），每个包的依赖装在各自的 `node_modules` 下，不会向上 hoist。
+>
+> 但 `vp pack` 构建时会将 `packages/language-server` 的入口打包为 `packages/vscode/dist/server.js`，运行时从这个产物 `require` 的各种依赖**必须能被 `packages/vscode` 的模块解析路径找到**。
+>
+> 因此，有些 language-server 用到的依赖（如 `volar-service-typescript`）需要在 `packages/vscode/package.json` 的 `dependencies` 中**显式重复声明**，否则运行时会出现 `MODULE_NOT_FOUND` 错误。如果你新加了某个 language-server 依赖后遇到这种错误，大概率是这个原因。
+
+使用`VSCode`打开文件夹打开项目根目录。
+
+1. 在左侧栏找到「运行和调试」面板（`Cmd+Shift+D`）
+2. 选择 "Launch Client" 配置
+3. 点击绿色的 ▶ 按钮（或使用键盘快捷键`F5`）
+4. 即可启动一个扩展开发宿主进程，打开另一个`vscode`窗口，开始调试项目。
+
+
 
 ## `volar labs` 插件
 

README-en.md

@@ -106,7 +106,7 @@ PR address: [https://github.com/material-extensions/vscode-material-icon-theme/p
 | `ets.lspDebugMode`                       | Enable ETS Language Server debug logging.                                | `boolean` | `false`                       |
 | `ets.ignoreWorkspaceLocalPropertiesFile` | Ignore auto infer the base SDK path from `local.properties` file in the local workspace.          | `boolean` | `false`                       |
 | `ets.linterVersion`                      | The version of the ArkTS linter to use. Set to 'off' to disable the linter. | `string`  | `"1.1"`                       |
-| `ets.resourceReferenceDiagnostic`        | 未匹配到的 $r() 资源引用的诊断级别                                                        | `string`  | `"error"`                     |
+| `ets.resourceReferenceDiagnostic`        | Diagnostic level for unmatched $r() resource references                                                        | `string`  | `"error"`                     |
 | `ets.localImagePath`                     | The path of the local image folder. The local image folder is used to store the images of the devices.
 
 In MacOS, the default path is `~/Library/Huawei/Sdk`; in Windows, the default path is `%APPDATA%\Local\Huawei\Sdk`.                              | `string`  | ``                            |
@@ -139,6 +139,10 @@ In MacOS, the default path is `~/Library/Huawei/Sdk`; in Windows, the default pa
 
 <!-- commands -->
 
+## Contributing 👩‍💻
+
+If you'd like to contribute to this project or build from source, please refer to [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 ## Star History 🌟
 
 [![Star History Chart](https://api.star-history.com/svg?repos=ohosvscode/arkTS&type=Date)](https://star-history.com/#ohosvscode/arkTS&Date)
@@ -149,7 +153,7 @@ In MacOS, the default path is `~/Library/Huawei/Sdk`; in Windows, the default pa
 
 - Telegram: [@GCZ_Zero](https://t.me/GCZ_Zero)
 - X (Twitter): [@GCZ_Zero](https://x.com/GCZ_Zero)
-- QQ: 1203970284，QQ Group: 746153004
+- QQ: 1203970284, QQ Group: 746153004
 - WeChat: gcz-zero
 
 ### Coffee ☕️

README.md

@@ -166,6 +166,10 @@ In order to run your app, type:
 Your app code is in demo/entry.
 ```
 
+## 参与开发 👩‍💻
+
+如果你想参与本项目的开发或从源码构建，请查阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+
 ## Star History 🌟
 
 [![Star History Chart](https://api.star-history.com/svg?repos=ohosvscode/arkTS&type=Date)](https://star-history.com/#ohosvscode/arkTS&Date)

packages/vscode/assets/create-project.md

@@ -0,0 +1,3 @@
+## Create ArkTS Project
+
+Create a new ArkTS project to start developing your OpenHarmony application.

packages/vscode/assets/create-project.zh-cn.md

@@ -0,0 +1,3 @@
+## 创建 ArkTS 项目
+
+创建一个新的 ArkTS 项目，开始编写您的鸿蒙应用。

packages/vscode/package.json

@@ -31,7 +31,6 @@
     "Linters",
     "Snippets",
     "Formatters",
-    "Themes",
     "Debuggers"
   ],
   "main": "./dist/client.js",
@@ -122,17 +121,15 @@
         "properties": {
           "projectRoot": {
             "type": "string",
-            "description": "Hvigor 项目根目录。"
+            "description": "Hvigor 项目根目录"
           },
           "moduleName": {
             "type": "string",
-            "description": "模块名称。",
-            "default": "entry"
+            "description": "模块名称，必填"
           },
           "productName": {
             "type": "string",
-            "description": "产品名称。",
-            "default": "default"
+            "description": "产品名称，默认 default"
           },
           "requiredDeviceType": {
             "type": "string",
@@ -591,6 +588,14 @@
             "media": {
               "markdown": "%walkthroughs.ArkTS-Walkthrough.steps.installOpenHarmonySDK.media.markdown%"
             }
+          },
+          {
+            "id": "ArkTS-Walkthrough-CreateProject",
+            "title": "%walkthroughs.ArkTS-Walkthrough.steps.createProject%",
+            "description": "%walkthroughs.ArkTS-Walkthrough.steps.createProject.description%",
+            "media": {
+              "markdown": "%walkthroughs.ArkTS-Walkthrough.steps.createProject.media.markdown%"
+            }
           }
         ]
       }
@@ -599,14 +604,15 @@
   "scripts": {
     "build": "tsx scripts/build.ts",
     "watch": "tsx scripts/watch.ts",
-    "pack": "tsx scripts/pre-process.ts && pnpm run build && vsce package",
+    "pack": "tsx scripts/pre-process.ts && pnpm run build && vsce package --no-dependencies",
     "postpack": "tsx scripts/clean-process.ts",
     "update": "vscode-ext-gen --output src/generated/meta.ts --locale zh-cn && vscode-ext-gen --output src/generated/meta.ts --locale zh-cn --readme ../../README.md && vscode-ext-gen --output src/generated/meta.ts --locale --readme ../../README-en.md",
     "ovsx": "ovsx",
     "vsce": "vsce"
   },
   "dependencies": {
-    "@napi-rs/wasm-runtime": "^1.0.7"
+    "@napi-rs/wasm-runtime": "^1.0.7",
+    "volar-service-typescript": "catalog:prod"
   },
   "devDependencies": {
     "@types/vscode": "^1.22.0"

packages/vscode/package.nls.json

@@ -55,6 +55,10 @@
   "project.createProject.submit": "Create",
   "project.createProject.title": "Create ArkTS Project",
   "project.openProject": "Open Project",
+  "project.writePath.blockedSystemPath": "Cannot write project to a system or unsafe directory.",
+  "project.writePath.fileExists": "A file already exists at the target path: {0}",
+  "project.writePath.invalid": "Please enter a valid save path.",
+  "project.writePath.zipSlip": "The template archive contains an unsafe file path.",
   "project.templateMarket.detail": "Detail",
   "project.templateMarket.downloadTo": "Choose where to download the template",
   "project.templateMarket.downloading": "Downloading template...",
@@ -185,6 +189,8 @@
   "sdk.error.SDKPathNotDirectory": "OpenHarmony SDK path must be a directory, please check the 'ets.sdkPath' in the IDE settings or the 'sdk.dir' in the local.properties file in the local workspace.",
   "sdk.error.SDKPathNotFound": "OpenHarmony SDK path not found, please check the 'ets.sdkPath' in the IDE settings or the 'sdk.dir' in the local.properties file in the local workspace.",
   "sdk.error.choiceSdkPathMasually": "Manually choose a OpenHarmony SDK path",
+  "sdk.error.autoDetectSdkPath": "Use default (Auto-detect from DevEco Studio)",
+  "sdk.error.sdkStructureInvalid": "Selected folder is not a valid OpenHarmony SDK, not found: {0}",
   "sdk.error.downloadOrChoiceSdkPath": "Download or choose a OpenHarmony SDK path",
   "sdk.error.languageServerError": "ArkTS Language Server Start Failed, please try to restart the IDE or check the OpenHarmony SDK path is correct. Error detail: {0}",
   "sdk.error.validSdkPath": "OpenHarmony SDK path is not set in global IDE configuration and local workspace local.properties file, the ETS Language Server will not work properly.",
@@ -230,6 +236,9 @@
   "walkthroughs.ArkTS-Walkthrough.steps.installOpenHarmonySDK": "Install OpenHarmony SDK",
   "walkthroughs.ArkTS-Walkthrough.steps.installOpenHarmonySDK.description": "Install OpenHarmony SDK to support ArkTS development. \n[Install OpenHarmony SDK](command:ets.installSDK)",
   "walkthroughs.ArkTS-Walkthrough.steps.installOpenHarmonySDK.media.markdown": "./assets/install-sdk.md",
+  "walkthroughs.ArkTS-Walkthrough.steps.createProject": "Create ArkTS Project",
+  "walkthroughs.ArkTS-Walkthrough.steps.createProject.description": "Create a new ArkTS project to start developing. \n[Create ArkTS Project](command:ets.createProject)",
+  "walkthroughs.ArkTS-Walkthrough.steps.createProject.media.markdown": "./assets/create-project.md",
   "walkthroughs.ArkTS-Walkthrough.title": "OpenHarmony ArkTS Setup",
   "tasks.error.hdcNotFoundInSystemEnvironmentVariables": "hdc command not found in system environment variables.",
   "tasks.error.hvigorNotFoundInSystemEnvironmentVariables": "hvigor or hvigorw command not found in system environment variables.",

packages/vscode/package.nls.zh-cn.json

@@ -122,6 +122,10 @@
   "project.createProject.submit": "创建",
   "project.createProject.title": "创建 ArkTS 项目",
   "project.openProject": "打开文件夹",
+  "project.writePath.blockedSystemPath": "不能将工程写入系统目录或不安全的路径。",
+  "project.writePath.fileExists": "目标路径已存在文件: {0}",
+  "project.writePath.invalid": "请输入有效的保存路径。",
+  "project.writePath.zipSlip": "模版压缩包包含不安全的文件路径。",
   "project.templateMarket.detail": "详情",
   "project.templateMarket.downloadTo": "选择将模版下载到何处",
   "project.templateMarket.downloading": "模版下载中...",
@@ -185,6 +189,8 @@
   "sdk.error.SDKPathNotDirectory": "OpenHarmony SDK 路径必须是一个目录, 请检查IDE设置中的“ets.sdkPath”或者本地工作区下的“local.properties”里的“sdk.dir”属性是否设置正确。",
   "sdk.error.SDKPathNotFound": "OpenHarmony SDK 路径不存在, 请检查IDE设置中的“ets.sdkPath”或者本地工作区下的“local.properties”里的“sdk.dir”属性是否设置正确。",
   "sdk.error.choiceSdkPathMasually": "手动选择一个 OpenHarmony SDK 路径",
+  "sdk.error.autoDetectSdkPath": "使用默认（自动从 DevEco Studio 检测）",
+  "sdk.error.sdkStructureInvalid": "所选文件夹不是有效的 OpenHarmony SDK，未找到: {0}",
   "sdk.error.downloadOrChoiceSdkPath": "下载或选择一个 OpenHarmony SDK 路径",
   "sdk.error.helpLabel": "帮助",
   "sdk.error.languageServerError": "ArkTS 语言服务器启动失败, 请尝试重启 IDE 或检查 OpenHarmony SDK 路径是否正确。错误详情: {0}",
@@ -237,6 +243,9 @@
   "walkthroughs.ArkTS-Walkthrough.steps.installOpenHarmonySDK": "安装 OpenHarmony SDK",
   "walkthroughs.ArkTS-Walkthrough.steps.installOpenHarmonySDK.description": "安装 OpenHarmony SDK 以支持 ArkTS 开发。\n[安装 OpenHarmony SDK](command:ets.installSDK)",
   "walkthroughs.ArkTS-Walkthrough.steps.installOpenHarmonySDK.media.markdown": "./assets/install-sdk.zh-cn.md",
+  "walkthroughs.ArkTS-Walkthrough.steps.createProject": "创建 ArkTS 项目",
+  "walkthroughs.ArkTS-Walkthrough.steps.createProject.description": "创建一个新的 ArkTS 项目，开始编写鸿蒙应用。\n[创建 ArkTS 项目](command:ets.createProject)",
+  "walkthroughs.ArkTS-Walkthrough.steps.createProject.media.markdown": "./assets/create-project.zh-cn.md",
   "walkthroughs.ArkTS-Walkthrough.title": "完成 OpenHarmony ArkTS 设置",
   "yes": "确定"
 }

packages/vscode/scripts/clean-process.ts

@@ -8,6 +8,15 @@ async function main() {
   fs.rmSync(path.resolve('node_modules'), { recursive: true, force: true })
   if (fs.existsSync(path.resolve('package-lock.json'))) fs.rmSync(path.resolve('package-lock.json'), { force: true })
   else globalLogger.warn('package-lock.json not found, skipping deletion')
+
+  const pkgJsonPath = path.resolve('package.json')
+  const backupPath = `${pkgJsonPath}.orig`
+  if (fs.existsSync(backupPath)) {
+    globalLogger.info('Restoring original package.json from backup...')
+    fs.copyFileSync(backupPath, pkgJsonPath)
+    fs.rmSync(backupPath)
+  }
+
   globalLogger.info('Reinstalling dependencies using pnpm...')
   execSync('pnpm install', { cwd: path.resolve('..', '..'), stdio: 'inherit' })
   globalLogger.success('✨ Dependencies cleaning process done!')

packages/vscode/scripts/pre-process.ts

@@ -18,6 +18,86 @@ export const PLATFORMS = {
   'web': ['wasm32'],
 }
 
+/**
+ * 读取 pnpm workspace catalog 定义，将 package.json 中的 catalog:xxx 替换为实际版本号。
+ * npm 不支持 catalog: 协议，因此 pre-process 使用 npm install 前必须先平展这些引用。
+ */
+function resolveCatalogDeps(pkgPath: string): void {
+  const workspaceRoot = path.resolve(pkgPath, '../..')
+  const workspaceFile = path.join(workspaceRoot, 'pnpm-workspace.yaml')
+  const pkgJsonPath = path.join(pkgPath, 'package.json')
+
+  if (!fs.existsSync(workspaceFile) || !fs.existsSync(pkgJsonPath)) return
+
+  const yamlLines = fs.readFileSync(workspaceFile, 'utf-8').split('\n')
+  const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'))
+
+  const catalogMap = new Map<string, string>()
+
+  let inCatalogs = false
+  let currentCatalog = ''
+
+  for (const rawLine of yamlLines) {
+    const line = rawLine.trimEnd()
+    const trimmed = line.trim()
+
+    if (trimmed === 'catalogs:') {
+      inCatalogs = true
+      currentCatalog = ''
+      continue
+    }
+
+    if (inCatalogs) {
+      if (trimmed === '' || trimmed.startsWith('#')) continue
+      // 如果碰到其他顶层键（如 catalog:），退出 catalogs 解析
+      if (/^[a-z]/i.test(line) && !line.startsWith(' ') && !line.startsWith('\t')) {
+        inCatalogs = false
+        continue
+      }
+      // 子 catalog 头，如 "  prod:" 或 "  dev:"
+      const catalogHeader = trimmed.match(/^(\w+):$/)
+      if (catalogHeader) {
+        currentCatalog = catalogHeader[1]
+        continue
+      }
+      // 依赖行，如 "    volar-service-typescript: volar-2.4"
+      const colonIdx = trimmed.indexOf(':')
+      if (colonIdx > 0) {
+        const depName = trimmed.slice(0, colonIdx).trim()
+        const depVersion = trimmed.slice(colonIdx + 1).trim().replace(/^['"]|['"]$/g, '')
+        catalogMap.set(depName, depVersion)
+        catalogMap.set(`${currentCatalog}:${depName}`, depVersion)
+      }
+    }
+  }
+
+  // 替换 package.json 中的 catalog 引用
+  function replaceInDeps(deps: Record<string, string> | undefined) {
+    if (!deps) return
+    for (const key of Object.keys(deps)) {
+      const val = deps[key]
+      if (typeof val === 'string' && val.startsWith('catalog:')) {
+        const catalogName = val.slice('catalog:'.length) || 'prod'
+        const lookupKey = `${catalogName}:${key}`
+        const resolved = catalogMap.get(lookupKey) || catalogMap.get(key)
+        if (resolved) {
+          globalLogger.info(`Resolved catalog dependency: ${key}@${val} -> ${resolved}`)
+          deps[key] = resolved
+        }
+        else {
+          globalLogger.warn(`Cannot resolve catalog dependency: ${key}@${val}, leaving unchanged`)
+        }
+      }
+    }
+  }
+
+  replaceInDeps(pkgJson.dependencies)
+  replaceInDeps(pkgJson.devDependencies)
+  replaceInDeps(pkgJson.optionalDependencies)
+
+  fs.writeFileSync(pkgJsonPath, `${JSON.stringify(pkgJson, null, 2)}\n`)
+}
+
 /**
  * This script is used to copy the `@arkts/project-detector` and
  * its dependencies to the `node_modules/@arkts/project-detector`
@@ -31,6 +111,13 @@ async function main() {
   globalLogger.info('Removing package-lock.json...')
   if (fs.existsSync(path.resolve('package-lock.json'))) fs.rmSync(path.resolve('package-lock.json'))
   else globalLogger.warn('package-lock.json not found, skipping deletion')
+
+  globalLogger.info('Resolving catalog dependencies for npm compatibility...')
+  const pkgJsonPath = path.join(path.resolve('.'), 'package.json')
+  const backupPath = `${pkgJsonPath}.orig`
+  fs.copyFileSync(pkgJsonPath, backupPath)
+  resolveCatalogDeps(path.resolve('.'))
+
   globalLogger.info('Installing dev & prod dependencies using npm...')
   const projectDetectorIdentifiers = collectIdentifiers(resolveDependenciesByIdentifier('@arkts/project-detector')).map((identifier) => {
     if (identifier === '@arkts/project-detector') return `${identifier}@next`