@hagicode/hagiscript 0.1.6 → 0.1.8

package/dist/runtime/runtime-state.js

@@ -0,0 +1,82 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export class RuntimeStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RuntimeStateError";
+    }
+}
+export function createInitialRuntimeState(manifest, paths) {
+    return {
+        schemaVersion: 1,
+        runtime: {
+            name: manifest.runtime.name,
+            version: manifest.runtime.version,
+            manifestPath: manifest.manifestPath
+        },
+        managedRoot: paths.root,
+        managedPaths: paths,
+        components: {},
+        lastOperation: null
+    };
+}
+export async function readRuntimeState(statePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(statePath, "utf8"));
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new RuntimeStateError(`Failed to read runtime state ${statePath}: ${message}`);
+    }
+    return validateRuntimeState(parsed, statePath);
+}
+export async function writeRuntimeState(statePath, state) {
+    await mkdir(dirname(statePath), { recursive: true });
+    await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+export function mergeRuntimeState(manifest, paths, state) {
+    const nextState = state ?? createInitialRuntimeState(manifest, paths);
+    return {
+        ...nextState,
+        runtime: {
+            name: manifest.runtime.name,
+            version: manifest.runtime.version,
+            manifestPath: manifest.manifestPath
+        },
+        managedRoot: paths.root,
+        managedPaths: paths,
+        components: { ...nextState.components }
+    };
+}
+function validateRuntimeState(value, statePath) {
+    if (!isRecord(value)) {
+        throw new RuntimeStateError(`Runtime state ${statePath} must be a JSON object.`);
+    }
+    if (value.schemaVersion !== 1) {
+        throw new RuntimeStateError(`Runtime state ${statePath} has unsupported schemaVersion ${String(value.schemaVersion)}.`);
+    }
+    if (!isRecord(value.runtime) || typeof value.runtime.name !== "string" || typeof value.runtime.version !== "string") {
+        throw new RuntimeStateError(`Runtime state ${statePath} is missing runtime metadata.`);
+    }
+    if (!isRecord(value.managedPaths)) {
+        throw new RuntimeStateError(`Runtime state ${statePath} is missing managedPaths.`);
+    }
+    if (!isRecord(value.components)) {
+        throw new RuntimeStateError(`Runtime state ${statePath} is missing components.`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMissingFileError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        error.code === "ENOENT");
+}
+//# sourceMappingURL=runtime-state.js.map

package/dist/runtime/runtime-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-state.js","sourceRoot":"","sources":["../../src/runtime/runtime-state.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagiscript",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Scoped npm package foundation for Hagiscript language tooling.",
   "license": "MIT",
   "homepage": "https://github.com/HagiCode-org/hagiscript#readme",
@@ -20,12 +20,14 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "hagiscript": "dist/cli.js"
+    "hagiscript": "dist/cli.js",
+    "hagicode-runtime": "bin/runtime"
   },
   "files": [
     "dist",
-    "README.md",
-    "README_cn.md"
+    "bin",
+    "runtime",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -35,6 +37,7 @@
     "format:check": "prettier --check .",
     "lint": "eslint .",
     "integration:installed-runtime": "node scripts/integration-installed-runtime.mjs",
+    "integration:runtime-management": "node scripts/integration-runtime-management.mjs",
     "pack:check": "node scripts/verify-package.mjs",
     "publish:check-prereqs": "node scripts/verify-npm-publish-prereqs.mjs",
     "publish:prepare-dev-version": "node scripts/prepare-dev-version.mjs",
@@ -59,7 +62,8 @@
   "dependencies": {
     "commander": "^14.0.1",
     "execa": "^9.6.1",
-    "semver": "^7.7.4"
+    "semver": "^7.7.4",
+    "yaml": "^2.8.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.38.0",

package/runtime/lib/runtime-script-lib.mjs

@@ -0,0 +1,531 @@
+import { spawn } from "node:child_process"
+import { createReadStream, createWriteStream } from "node:fs"
+import { access, chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import process from "node:process"
+import { createGunzip } from "node:zlib"
+import { pipeline } from "node:stream/promises"
+
+export function readRuntimeScriptContext() {
+  return {
+    runtimeRoot: requiredEnv("HAGISCRIPT_RUNTIME_ROOT"),
+    runtimeHome: requiredEnv("HAGICODE_RUNTIME_HOME"),
+    runtimeDataHome: requiredEnv("HAGICODE_RUNTIME_DATA_HOME"),
+    binDir: requiredEnv("HAGISCRIPT_RUNTIME_BIN_DIR"),
+    configDir: requiredEnv("HAGISCRIPT_RUNTIME_CONFIG_DIR"),
+    logsDir: requiredEnv("HAGISCRIPT_RUNTIME_LOGS_DIR"),
+    dataDir: requiredEnv("HAGISCRIPT_RUNTIME_DATA_DIR"),
+    statePath: requiredEnv("HAGISCRIPT_RUNTIME_STATE_PATH"),
+    componentName: requiredEnv("HAGISCRIPT_RUNTIME_COMPONENT_NAME"),
+    componentType: requiredEnv("HAGISCRIPT_RUNTIME_COMPONENT_TYPE"),
+    componentRoot: requiredEnv("HAGISCRIPT_RUNTIME_COMPONENT_ROOT"),
+    componentConfigDir: requiredEnv("HAGISCRIPT_RUNTIME_COMPONENT_CONFIG_DIR"),
+    componentDataDir: requiredEnv("HAGISCRIPT_RUNTIME_COMPONENT_DATA_DIR"),
+    componentLogsDir: requiredEnv("HAGISCRIPT_RUNTIME_COMPONENT_LOGS_DIR"),
+    componentPm2Home: requiredEnv("HAGISCRIPT_RUNTIME_COMPONENT_PM2_HOME"),
+    templateDir: requiredEnv("HAGISCRIPT_RUNTIME_TEMPLATE_DIR"),
+    componentVersion: process.env.HAGISCRIPT_RUNTIME_COMPONENT_VERSION?.trim() || null,
+    vendoredRepository: process.env.HAGISCRIPT_RUNTIME_VENDORED_REPOSITORY?.trim() || "HagiCode-org/vendered",
+    vendoredTag:
+      process.env.HAGISCRIPT_RUNTIME_VENDORED_TAG?.trim() || "v2026.0506.0029",
+    vendoredBaseUrl: process.env.HAGISCRIPT_RUNTIME_VENDORED_BASE_URL?.trim() || "https://github.com",
+    phase: process.env.HAGISCRIPT_RUNTIME_PHASE?.trim() || "install",
+    purge: process.env.HAGISCRIPT_RUNTIME_PURGE === "1"
+  }
+}
+
+export async function ensureDirectory(directory) {
+  await mkdir(directory, { recursive: true })
+}
+
+export async function writeJsonFile(filePath, value) {
+  await ensureDirectory(path.dirname(filePath))
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8")
+}
+
+export async function writeComponentMarker(context, extra = {}) {
+  const markerPath = path.join(context.componentRoot, ".hagicode-runtime.json")
+  await writeJsonFile(markerPath, {
+    component: context.componentName,
+    type: context.componentType,
+    version: context.componentVersion,
+    phase: context.phase,
+    runtimeRoot: context.runtimeRoot,
+    generatedAt: new Date().toISOString(),
+    ...extra
+  })
+  return markerPath
+}
+
+export async function materializeTemplate(templateName, destinationPath, variables) {
+  const templatePath = path.join(readRuntimeScriptContext().templateDir, templateName)
+  const template = await readFile(templatePath, "utf8")
+  let rendered = template
+
+  for (const [key, value] of Object.entries(variables)) {
+    rendered = rendered.replaceAll(`{{${key}}}`, String(value))
+  }
+
+  await ensureDirectory(path.dirname(destinationPath))
+  await writeFile(destinationPath, rendered, "utf8")
+  return destinationPath
+}
+
+export async function writeNodeEntrypoint(filePath, message) {
+  await ensureDirectory(path.dirname(filePath))
+  await writeFile(
+    filePath,
+    `#!/usr/bin/env node\nprocess.stdout.write(${JSON.stringify(message)} + "\\n")\n`,
+    "utf8"
+  )
+  await makeExecutable(filePath)
+  return filePath
+}
+
+export async function writeCommandWrapper(binDir, commandName, scriptPath) {
+  await ensureDirectory(binDir)
+  const nodeWrapperPath = path.join(binDir, process.platform === "win32" ? "node.cmd" : "node")
+
+  if (process.platform === "win32") {
+    const wrapperPath = path.join(binDir, `${commandName}.cmd`)
+    const relativeTarget = path.relative(path.dirname(wrapperPath), scriptPath).replaceAll("/", "\\")
+    const relativeNode = path.relative(path.dirname(wrapperPath), nodeWrapperPath).replaceAll("/", "\\")
+    await writeFile(
+      wrapperPath,
+      `@echo off\r\nset "HAGISCRIPT_NODE=%~dp0\\${relativeNode}"\r\nif exist "%HAGISCRIPT_NODE%" (\r\n  "%HAGISCRIPT_NODE%" "%~dp0\\${relativeTarget}" %*\r\n) else (\r\n  node "%~dp0\\${relativeTarget}" %*\r\n)\r\n`,
+      "utf8"
+    )
+    return wrapperPath
+  }
+
+  const wrapperPath = path.join(binDir, commandName)
+  const relativeTarget = path.relative(path.dirname(wrapperPath), scriptPath).replaceAll("\\", "/")
+  const relativeNode = path.relative(path.dirname(wrapperPath), nodeWrapperPath).replaceAll("\\", "/")
+  await writeFile(
+    wrapperPath,
+    `#!/usr/bin/env sh
+node_cmd="$(dirname "$0")/${relativeNode}"
+if [ -x "$node_cmd" ]; then
+  exec "$node_cmd" "$(dirname "$0")/${relativeTarget}" "$@"
+fi
+exec node "$(dirname "$0")/${relativeTarget}" "$@"
+`,
+    "utf8"
+  )
+  await makeExecutable(wrapperPath)
+  return wrapperPath
+}
+
+export async function installVendoredPackage(context, options) {
+  const { repository, baseUrl } = parseGitHubRepositoryConfig(
+    context.vendoredRepository,
+    context.vendoredBaseUrl
+  )
+  const releaseTag = context.vendoredTag
+  const platform = normalizeVendoredPlatform(process.platform)
+  const arch = normalizeVendoredArchitecture(process.arch)
+  const assetName = buildVendoredAssetName({
+    packageName: options.packageName,
+    releaseTag,
+    platform,
+    arch
+  })
+  const assetUrl = buildVendoredAssetUrl(baseUrl, repository, releaseTag, assetName)
+
+  const stagingRoot = await mkdtemp(path.join(tmpdir(), `hagiscript-vendored-${options.packageName}-`))
+
+  try {
+    const archivePath = path.join(stagingRoot, assetName)
+    const extractRoot = path.join(stagingRoot, "extract")
+    await downloadVendoredAsset(assetUrl, archivePath)
+    const extractedRoot = await extractVendoredArchive(
+      archivePath,
+      extractRoot,
+      path.extname(assetName).toLowerCase() === ".zip" ? "zip" : "tar.gz"
+    )
+    await replaceDirectory(extractedRoot, options.prefixRoot)
+
+    const entrypointPath = path.join(options.prefixRoot, options.entrypointRelativePath)
+    await access(entrypointPath)
+
+    return {
+      entrypointPath,
+      releaseRepository: repository,
+      releaseTag,
+      releaseName: releaseTag.replace(/^v/u, ""),
+      releaseUrl: `${baseUrl}/${repository}/releases/tag/${encodeURIComponent(releaseTag)}`,
+      releaseAssetName: assetName,
+      releaseAssetUrl: assetUrl
+    }
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true })
+  }
+}
+
+export async function writeManagedPackageLauncher(filePath, options) {
+  await ensureDirectory(path.dirname(filePath))
+  const configLoader =
+    options.serviceKind === "omniroute"
+      ? `
+const runtimeConfig = await loadOmnirouteConfig()
+const runtimeEnv = {
+  ...(runtimeConfig.dataDir ? { DATA_DIR: runtimeConfig.dataDir } : {}),
+  ...(runtimeConfig.logDir ? { LOG_DIR: runtimeConfig.logDir } : {}),
+  ...(runtimeConfig.port ? { PORT: runtimeConfig.port } : {})
+}
+`
+      : ""
+  const configHelpers =
+    options.serviceKind === "omniroute"
+      ? `
+async function loadOmnirouteConfig() {
+  try {
+    const [{ readFile }, { parse }] = await Promise.all([
+      import("node:fs/promises"),
+      import("yaml")
+    ])
+    const loaded = parse(await readFile(configPath, "utf8"))
+    const listen = typeof loaded?.listen === "string" ? loaded.listen : ""
+    const portMatch = listen.match(/:(\\d+)$/u)
+    return {
+      dataDir: typeof loaded?.dataDir === "string" ? loaded.dataDir : ${JSON.stringify(
+          options.defaultEnv?.DATA_DIR ?? ""
+        )},
+      logDir: typeof loaded?.logDir === "string" ? loaded.logDir : ${JSON.stringify(
+          options.defaultEnv?.LOG_DIR ?? ""
+        )},
+      port: portMatch?.[1] ?? ${JSON.stringify(options.defaultEnv?.PORT ?? "")}
+    }
+  } catch {
+    return {
+      dataDir: ${JSON.stringify(options.defaultEnv?.DATA_DIR ?? "")},
+      logDir: ${JSON.stringify(options.defaultEnv?.LOG_DIR ?? "")},
+      port: ${JSON.stringify(options.defaultEnv?.PORT ?? "")}
+    }
+  }
+}
+`
+      : ""
+
+  await writeFile(
+    filePath,
+    `#!/usr/bin/env node
+import { spawn } from "node:child_process"
+
+const entrypointPath = ${JSON.stringify(options.entrypointPath)}
+const configPath = ${JSON.stringify(options.configPath)}
+const baseArgs = ${JSON.stringify(options.baseArgs ?? [])}
+const baseEnv = ${JSON.stringify(options.defaultEnv ?? {})}
+${configLoader}
+const child = spawn(
+  process.execPath,
+  [entrypointPath, ...baseArgs, ...process.argv.slice(2)],
+  {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      ...baseEnv,
+      ${options.serviceKind === "omniroute" ? "...runtimeEnv" : ""}
+    }
+  }
+)
+
+const forwardSignal = (signal) => {
+  if (!child.killed) {
+    child.kill(signal)
+  }
+}
+
+process.on("SIGINT", () => forwardSignal("SIGINT"))
+process.on("SIGTERM", () => forwardSignal("SIGTERM"))
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal)
+    return
+  }
+
+  process.exit(code ?? 0)
+})
+
+child.on("error", (error) => {
+  process.stderr.write(String(error?.stack ?? error) + "\\n")
+  process.exit(1)
+})
+${configHelpers}
+`,
+    "utf8"
+  )
+  await makeExecutable(filePath)
+  return filePath
+}
+
+function requiredEnv(name) {
+  const value = process.env[name]?.trim()
+
+  if (!value) {
+    throw new Error(`Missing runtime script environment variable: ${name}`)
+  }
+
+  return value
+}
+
+async function makeExecutable(filePath) {
+  if (process.platform === "win32") {
+    return
+  }
+
+  await chmod(filePath, 0o755)
+}
+
+function runManagedCommand(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      env: options.env,
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    })
+    let stdout = ""
+    let stderr = ""
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString()
+    })
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString()
+    })
+    child.on("error", reject)
+    child.on("exit", (code, signal) => {
+      if (code === 0) {
+        resolve({ stdout, stderr })
+        return
+      }
+
+      reject(
+        new Error(
+          `Managed command failed: ${command} ${args.join(" ")} (code=${code ?? "null"}, signal=${signal ?? "null"})\n${stderr || stdout}`.trim()
+        )
+      )
+    })
+  })
+}
+
+function parseGitHubRepositoryConfig(repositoryValue, baseUrlValue) {
+  const trimmedRepository = String(repositoryValue || "").trim()
+  const repository =
+    trimmedRepository.startsWith("https://github.com/")
+      ? trimmedRepository
+          .replace(/^https:\/\/github\.com\//u, "")
+          .replace(/\.git$/u, "")
+          .replace(/\/+$/u, "")
+      : trimmedRepository
+
+  if (!/^[^/]+\/[^/]+$/u.test(repository)) {
+    throw new Error(`Invalid vendored GitHub repository: ${trimmedRepository}`)
+  }
+
+  return {
+    repository,
+    baseUrl: String(baseUrlValue || "https://github.com").replace(/\/+$/u, "")
+  }
+}
+
+function buildVendoredAssetName(options) {
+  const releaseVersion = normalizeVendoredReleaseVersion(options.releaseTag)
+  return `${options.packageName}-${releaseVersion}-${options.platform}-${options.arch}${getVendoredArchiveExtension(options.platform)}`
+}
+
+function buildVendoredAssetUrl(baseUrl, repository, releaseTag, assetName) {
+  return `${baseUrl}/${repository}/releases/download/${encodeURIComponent(releaseTag)}/${encodeURIComponent(assetName)}`
+}
+
+function normalizeVendoredReleaseVersion(releaseTag) {
+  const normalized = String(releaseTag || "").trim().replace(/^v/u, "")
+  if (!normalized) {
+    throw new Error(`Invalid vendored release tag: ${String(releaseTag)}`)
+  }
+
+  return normalized
+}
+
+function normalizeVendoredPlatform(platform) {
+  switch (platform) {
+    case "darwin":
+      return "macos"
+    case "win32":
+      return "windows"
+    default:
+      return "linux"
+  }
+}
+
+function normalizeVendoredArchitecture(arch) {
+  switch (String(arch).toLowerCase()) {
+    case "x64":
+      return "amd64"
+    case "arm64":
+    case "aarch64":
+      return "arm64"
+    default:
+      throw new Error(`Unsupported vendored runtime architecture: ${arch}`)
+  }
+}
+
+function getVendoredArchiveExtension(platform) {
+  return platform === "windows" ? ".zip" : ".tar.gz"
+}
+
+async function downloadVendoredAsset(url, destinationPath) {
+  const response = await globalThis.fetch(url)
+
+  if (!response.ok) {
+    throw new Error(`Failed to download vendored asset ${url}: HTTP ${response.status}`)
+  }
+
+  if (!response.body) {
+    throw new Error(`Failed to download vendored asset ${url}: empty response body.`)
+  }
+
+  await ensureDirectory(path.dirname(destinationPath))
+  const file = createWriteStream(destinationPath)
+
+  const reader = response.body.getReader()
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) {
+        break
+      }
+
+      if (!file.write(value)) {
+        await new Promise((resolve) => file.once("drain", resolve))
+      }
+    }
+
+    await new Promise((resolve, reject) =>
+      file.end((error) => (error ? reject(error) : resolve()))
+    )
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+async function extractVendoredArchive(archivePath, stagingDirectory, archiveKind) {
+  await rm(stagingDirectory, { recursive: true, force: true })
+  await mkdir(stagingDirectory, { recursive: true })
+
+  if (archiveKind === "zip") {
+    await extractZipArchive(archivePath, stagingDirectory)
+  } else {
+    await extractTarGzArchive(archivePath, stagingDirectory)
+  }
+
+  const entries = await readdir(stagingDirectory, { withFileTypes: true })
+  const directories = entries.filter((entry) => entry.isDirectory())
+
+  if (directories.length !== 1) {
+    throw new Error(
+      `Expected exactly one extracted vendored root in ${stagingDirectory}, found ${directories.length}.`
+    )
+  }
+
+  return path.join(stagingDirectory, directories[0].name)
+}
+
+async function extractZipArchive(archivePath, destination) {
+  if (process.platform === "win32") {
+    await runManagedCommand("powershell.exe", [
+      "-NoLogo",
+      "-NoProfile",
+      "-Command",
+      `Expand-Archive -Path '${escapePowerShell(archivePath.replaceAll("/", "\\"))}' -DestinationPath '${escapePowerShell(destination.replaceAll("/", "\\"))}' -Force`
+    ])
+    return
+  }
+
+  try {
+    await runManagedCommand("unzip", ["-q", archivePath, "-d", destination])
+  } catch {
+    await runManagedCommand("bsdtar", ["-xf", archivePath, "-C", destination])
+  }
+}
+
+async function extractTarGzArchive(archivePath, destination) {
+  try {
+    await runManagedCommand("tar", ["-xzf", archivePath, "-C", destination])
+  } catch {
+    await extractTarGzWithNode(archivePath, destination)
+  }
+}
+
+async function extractTarGzWithNode(archivePath, destination) {
+  const tarPath = `${archivePath}.tar`
+
+  try {
+    await pipeline(
+      createReadStream(archivePath),
+      createGunzip(),
+      createWriteStream(tarPath)
+    )
+    await extractTarBuffer(await readFile(tarPath), destination)
+  } finally {
+    await rm(tarPath, { force: true }).catch(() => undefined)
+  }
+}
+
+async function extractTarBuffer(buffer, destination) {
+  let offset = 0
+
+  while (offset + 512 <= buffer.length) {
+    const header = buffer.subarray(offset, offset + 512)
+    if (header.every((byte) => byte === 0)) {
+      break
+    }
+
+    const name = header.toString("utf8", 0, 100).replace(/\0.*$/u, "")
+    const sizeText = header
+      .toString("utf8", 124, 136)
+      .replace(/\0.*$/u, "")
+      .trim()
+    const typeFlag = header.toString("utf8", 156, 157)
+    const size = parseInt(sizeText || "0", 8)
+    const outputPath = safeArchiveJoin(destination, name)
+
+    if (typeFlag === "5") {
+      await mkdir(outputPath, { recursive: true })
+    } else if (typeFlag === "0" || typeFlag === "") {
+      await mkdir(path.dirname(outputPath), { recursive: true })
+      await writeFile(outputPath, buffer.subarray(offset + 512, offset + 512 + size))
+    }
+
+    offset += 512 + Math.ceil(size / 512) * 512
+  }
+}
+
+function safeArchiveJoin(root, entryName) {
+  const normalized = path.join(root, entryName)
+  const relativePath = path.relative(root, normalized)
+
+  if (
+    !entryName ||
+    relativePath.startsWith("..") ||
+    relativePath.includes(`${path.sep}..${path.sep}`) ||
+    path.isAbsolute(entryName)
+  ) {
+    throw new Error(`Vendored archive entry escapes the extraction root: ${entryName}`)
+  }
+
+  return normalized
+}
+
+async function replaceDirectory(sourceDirectory, targetDirectory) {
+  await rm(targetDirectory, { recursive: true, force: true })
+  await ensureDirectory(path.dirname(targetDirectory))
+  await rename(sourceDirectory, targetDirectory)
+}
+
+function escapePowerShell(value) {
+  return value.replaceAll("'", "''")
+}