@temporalio/create 0.22.0 → 1.0.0-rc.1

package/README.md

@@ -2,6 +2,6 @@
 
 [![NPM](https://img.shields.io/npm/v/@temporalio/create?style=for-the-badge)](https://www.npmjs.com/package/@temporalio/create)
 
-Project initializer for [Temporal](https://temporal.io)'s [TypeScript SDK](https://docs.temporal.io/docs/typescript/introduction/).
+Project initializer for [Temporal](https://temporal.io)'s [TypeScript SDK](https://docs.temporal.io/typescript/introduction/).
 
-[`@temporalio/create` documentation](https://docs.temporal.io/docs/typescript/package-initializer)
+[`@temporalio/create` documentation](https://docs.temporal.io/typescript/package-initializer)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/create",
-  "version": "0.22.0",
+  "version": "1.0.0-rc.1",
   "description": "Create a Temporal project from template",
   "main": "cli.js",
   "bin": "cli.js",
@@ -14,33 +14,30 @@
     "init",
     "workflow"
   ],
-  "files": [
-    "lib"
-  ],
   "author": "Roey Berman <roey@temporal.io>",
   "license": "MIT",
   "dependencies": {
     "async-retry": "^1.3.3",
-    "chalk": "^2.4.2",
-    "chalk-template": "^0.2.0",
-    "commander": "^8.2.0",
+    "chalk": "^5.0.1",
+    "chalk-template": "^0.4.0",
+    "commander": "^9.3.0",
     "dedent": "^0.7.0",
-    "glob": "^7.2.0",
-    "got": "^10.7.0",
-    "prompts": "^2.4.1",
-    "tar": "^4.4.10",
+    "glob": "^8.0.3",
+    "got": "^12.1.0",
+    "prompts": "^2.4.2",
+    "tar": "^6.1.11",
     "update-check": "1.5.4",
-    "validate-npm-package-name": "^3.0.0"
+    "validate-npm-package-name": "^4.0.0"
   },
   "devDependencies": {
-    "@types/async-retry": "^1.4.2",
+    "@types/async-retry": "^1.4.4",
     "@types/cross-spawn": "^6.0.2",
     "@types/got": "^9.6.12",
-    "@types/node": "^16.7.10",
-    "@types/prompts": "2.0.1",
-    "@types/rimraf": "^3.0.0",
-    "@types/tar": "^4.0.3",
-    "@types/validate-npm-package-name": "^3.0.0"
+    "@types/node": "^18.0.0",
+    "@types/prompts": "2.0.14",
+    "@types/rimraf": "^3.0.2",
+    "@types/tar": "^6.1.1",
+    "@types/validate-npm-package-name": "^4.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -48,5 +45,10 @@
   "engines": {
     "node": ">=14.0.0"
   },
-  "gitHead": "3aa1f14982bd170d21b728cbf016dc4f1b595a76"
+  "files": [
+    "cli.js",
+    "src",
+    "lib"
+  ],
+  "gitHead": "723de0fbc7a04e68084ec99453578e7027eb3803"
 }

package/src/create-project.ts

@@ -0,0 +1,220 @@
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/create-app.ts
+import retry from 'async-retry';
+import chalk from 'chalk';
+import chalkTemplate from 'chalk-template';
+import path from 'path';
+import prompts from 'prompts';
+import { access, rm, readFile } from 'fs/promises';
+
+import {
+  downloadAndExtractSample,
+  downloadAndExtractRepo,
+  getRepoInfo,
+  hasSample,
+  checkForPackageJson,
+  RepoInfo,
+} from './helpers/samples.js';
+import { makeDir } from './helpers/make-dir.js';
+import { tryGitInit } from './helpers/git.js';
+import { install, updateNodeVersion, replaceTemporalVersion } from './helpers/install.js';
+import { testIfThisComputerIsOnline } from './helpers/is-online.js';
+import { isWriteable } from './helpers/is-writeable.js';
+import { getErrorCode } from './helpers/get-error-code.js';
+import { stripSnipComments } from './helpers/strip-snip-comments.js';
+import { fetchSamples } from './helpers/fetch-samples.js';
+
+export class DownloadError extends Error {}
+
+export async function createApp({
+  appPath,
+  useYarn,
+  gitInit,
+  temporalioVersion,
+  sample,
+  samplePath,
+}: {
+  appPath: string;
+  useYarn: boolean;
+  gitInit?: boolean;
+  temporalioVersion?: string;
+  sample: string;
+  samplePath?: string;
+}): Promise<void> {
+  let repoInfo: RepoInfo | undefined;
+  let repoUrl: URL | undefined;
+
+  const isOnline = await testIfThisComputerIsOnline();
+  if (!isOnline) {
+    console.error(`Unable to reach ${chalk.bold(`github.com`)}. Perhaps you are not connected to the internet?`);
+    process.exit(1);
+  }
+
+  try {
+    repoUrl = new URL(sample);
+  } catch (error) {
+    if (getErrorCode(error) !== 'ERR_INVALID_URL') {
+      console.error(error);
+      process.exit(1);
+    }
+  }
+
+  if (repoUrl) {
+    if (repoUrl.origin !== 'https://github.com') {
+      console.error(
+        `Invalid URL: ${chalk.red(
+          `"${sample}"`
+        )}. Only GitHub repositories are supported. Please use a GitHub URL and try again.`
+      );
+      process.exit(1);
+    }
+
+    try {
+      repoInfo = await getRepoInfo(repoUrl, samplePath);
+      await checkForPackageJson(repoInfo);
+    } catch (e) {
+      console.error(e);
+      process.exit(1);
+    }
+  } else if (sample !== '__internal-testing-retry') {
+    const found = await hasSample(sample);
+
+    if (!found) {
+      console.error(
+        `Could not locate a sample named ${chalk.red(`"${sample}"`)}. It could be due to the following:\n`,
+        `1. Your spelling of sample ${chalk.red(`"${sample}"`)} might be incorrect.\n`,
+        `2. You might not be connected to the internet.\n`
+      );
+      const samples = await fetchSamples();
+      console.error(`Available samples:\n\n${samples.join('\n')}\n`);
+      process.exit(1);
+    }
+  }
+
+  const root = path.resolve(appPath);
+
+  if (!(await isWriteable(path.dirname(root)))) {
+    console.error('The application path is not writable, please check folder permissions and try again.');
+    console.error('It is likely you do not have write permissions for this folder.');
+    process.exit(1);
+  }
+
+  const appName = path.basename(root);
+
+  console.log(`Creating a new Temporal project in ${chalk.green(root)}/`);
+  console.log();
+
+  let directoryExists = true;
+
+  try {
+    await access(root);
+  } catch (error: any) {
+    const code = getErrorCode(error);
+
+    if (code === 'ENOENT') {
+      directoryExists = false;
+    } else if (code === 'EACCES') {
+      console.error(`Unable to access directory ${chalk.bold(root + '/')} (Error: permission denied)`);
+      process.exit(1);
+    } else {
+      throw error;
+    }
+  }
+
+  if (directoryExists) {
+    const res = await prompts({
+      type: 'confirm',
+      name: 'shouldReplace',
+      message: `Directory ${chalk.green(root + '/')} already exists. Would you like to replace it?`,
+    });
+
+    if (!res.shouldReplace) {
+      console.error('Exiting. You can re-run this command with a different project name.');
+      process.exit(1);
+    }
+
+    await rm(root, { recursive: true, force: true, maxRetries: 5 });
+  }
+
+  try {
+    await makeDir(root);
+  } catch (error) {
+    if (getErrorCode(error) === 'EACCES') {
+      console.error(`Unable to cd into directory ${chalk.bold(root + '/')} (Error: permission denied)`);
+      process.exit(1);
+    } else {
+      throw error;
+    }
+  }
+
+  /**
+   * If a sample repository is provided, clone it.
+   */
+  try {
+    if (repoInfo) {
+      const repoInfo2 = repoInfo;
+      console.log(`Downloading files from repo ${chalk.cyan(sample)}. This might take a moment.`);
+      console.log();
+      await retry(() => downloadAndExtractRepo(root, repoInfo2), {
+        retries: 3,
+      });
+    } else {
+      console.log(`Downloading files for sample ${chalk.cyan(sample)}. This might take a moment.`);
+      console.log();
+      await retry(() => downloadAndExtractSample(root, sample), {
+        retries: 3,
+      });
+      await stripSnipComments(root);
+    }
+  } catch (reason) {
+    let message = 'Unable to download';
+    if (reason instanceof Error) {
+      message = reason.message;
+    }
+
+    throw new DownloadError(message);
+  }
+
+  console.log('Installing packages. This might take a couple of minutes.');
+  console.log();
+
+  await updateNodeVersion({ root });
+  if (temporalioVersion) {
+    await replaceTemporalVersion({ root, useYarn, temporalioVersion });
+  }
+
+  await install({ root, useYarn });
+
+  console.log();
+
+  if (await tryGitInit(root, gitInit)) {
+    console.log('Initialized a git repository.');
+  }
+
+  const messageFile = path.join(root, '.post-create');
+
+  console.log();
+  console.log(`${chalk.green('Success!')} Created project ${chalk.bold(appName)} at:`);
+  console.log();
+  console.log(chalk.bold(appPath + '/'));
+  console.log();
+
+  try {
+    await access(messageFile);
+    const message = await readFile(messageFile, 'utf8');
+
+    // Hack for creating a TemplateStringsArray
+    // Required by chalk-template
+    class MockTemplateString extends Array implements TemplateStringsArray {
+      constructor(public readonly raw: string[]) {
+        super();
+      }
+    }
+    console.log(chalkTemplate(new MockTemplateString([message])));
+    await rm(messageFile);
+  } catch (error) {
+    const code = getErrorCode(error);
+    if (code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}

package/src/helpers/fetch-samples.ts

@@ -0,0 +1,25 @@
+import got from 'got';
+
+const SAMPLE_REPO_CONTENTS = 'https://api.github.com/repos/temporalio/samples-typescript/contents/';
+
+interface File {
+  name: string;
+  type: string;
+}
+
+export async function fetchSamples(): Promise<string[]> {
+  let response;
+
+  try {
+    // https://github.com/sindresorhus/got/blob/main/documentation/3-streams.md#response-1
+    response = await got(SAMPLE_REPO_CONTENTS);
+  } catch (error) {
+    throw new Error(`Unable to reach github.com`);
+  }
+
+  const files = JSON.parse(response.body) as File[];
+
+  return files
+    .filter((file) => file.type === 'dir' && file.name !== 'test' && !file.name.startsWith('.'))
+    .map(({ name }) => name);
+}

package/src/helpers/get-error-code.ts

@@ -0,0 +1,11 @@
+interface ErrorWithCode {
+  code: string;
+}
+
+export function getErrorCode(error: unknown): string {
+  if ((error as ErrorWithCode).code !== undefined && typeof (error as ErrorWithCode).code === 'string') {
+    return (error as ErrorWithCode).code;
+  } else {
+    return '';
+  }
+}

package/src/helpers/git.ts

@@ -0,0 +1,79 @@
+/* eslint-disable no-empty */
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/helpers/git.ts
+import { execSync } from 'child_process';
+import { rm } from 'fs/promises';
+import path from 'path';
+import prompts from 'prompts';
+
+const NOT_A_GIT_REPOSITORY_STATUS_CODE = 128;
+
+function isInGitRepository(): boolean {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { stdio: 'ignore' });
+    return true;
+  } catch (error: any) {
+    if (error.status === NOT_A_GIT_REPOSITORY_STATUS_CODE) {
+      return false;
+    } else {
+      // Unknown error. To be safe, assume we're in a repo.
+      return true;
+    }
+  }
+}
+
+const HG_ERROR_STATUS_CODE = 255;
+
+function isInMercurialRepository(): boolean {
+  try {
+    execSync('hg --cwd . root', { stdio: 'ignore' });
+    return true;
+  } catch (error: any) {
+    // There isn't anything more specific about `error` that we can pattern match against
+    if (error.status === HG_ERROR_STATUS_CODE && /Command failed/.test(error.message)) {
+      return false;
+    } else {
+      // Unknown error. To be safe, assume we're in a repo.
+      return true;
+    }
+  }
+}
+
+export async function tryGitInit(root: string, useGit?: boolean): Promise<boolean> {
+  if (useGit === false) {
+    return false;
+  }
+  let didInit = false;
+  const exec = (command: string) => execSync(command, { stdio: 'ignore', cwd: root });
+
+  try {
+    // If user didn't include --use-git, and they might be in an existing repo,
+    // ask before `git init`ing
+    if (useGit === undefined && (isInGitRepository() || isInMercurialRepository())) {
+      const res = await prompts({
+        type: 'confirm',
+        name: 'shouldInit',
+        message: `Would you like me to initialize a git repository for the project?`,
+      });
+
+      if (!res.shouldInit) {
+        return false;
+      }
+    }
+
+    exec('git init');
+    didInit = true;
+
+    exec('git checkout -b main');
+
+    exec('git add -A');
+    exec('git commit -m "Initial commit from @temporalio/create"');
+    return true;
+  } catch (e) {
+    if (didInit) {
+      try {
+        await rm(path.join(root, '.git'), { recursive: true, force: true });
+      } catch (_) {}
+    }
+    return false;
+  }
+}

package/src/helpers/install.ts

@@ -0,0 +1,62 @@
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/helpers/install.ts
+import { readFile, writeFile } from 'fs/promises';
+
+import { spawn } from './subprocess.js';
+import { isUrlOk } from './samples.js';
+
+interface InstallArgs {
+  root: string;
+
+  /**
+   * Indicate whether to install packages using Yarn.
+   */
+  useYarn?: boolean;
+  temporalioVersion?: string;
+}
+
+/**
+ * Spawn a package manager installation with either Yarn or NPM.
+ *
+ * @returns A Promise that resolves once the installation is finished.
+ */
+export function install({ root, useYarn }: InstallArgs): Promise<void> {
+  const npm = /^win/.test(process.platform) ? 'npm.cmd' : 'npm';
+  const command: string = useYarn ? 'yarn' : npm;
+
+  return spawn(command, ['install'], {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...process.env, ADBLOCK: '1', DISABLE_OPENCOLLECTIVE: '1' },
+  });
+}
+
+export async function updateNodeVersion({ root }: InstallArgs): Promise<void> {
+  const currentNodeVersion = +process.versions.node.split('.')[0];
+  const versionAlreadyInPackageJson = 16;
+  const minimumValidVersion = 14;
+
+  if (currentNodeVersion >= minimumValidVersion && currentNodeVersion !== versionAlreadyInPackageJson) {
+    const packageName = `@tsconfig/node${currentNodeVersion}`;
+    const fileName = `${root}/package.json`;
+
+    const packageExists = await isUrlOk(`https://registry.npmjs.org/${packageName}`);
+    if (packageExists) {
+      let fileString = (await readFile(fileName)).toString();
+      await writeFile(fileName, fileString.replace(`@tsconfig/node${versionAlreadyInPackageJson}`, packageName));
+
+      const tsconfigJson = `${root}/tsconfig.json`;
+      fileString = (await readFile(tsconfigJson)).toString();
+      await writeFile(tsconfigJson, fileString.replace(`@tsconfig/node${versionAlreadyInPackageJson}`, packageName));
+    }
+
+    await writeFile(`${root}/.nvmrc`, currentNodeVersion.toString());
+  }
+}
+
+export async function replaceTemporalVersion({ root, temporalioVersion }: InstallArgs): Promise<void> {
+  const fileName = `${root}/package.json`;
+
+  const packageJson = JSON.parse(await readFile(fileName, 'utf8'));
+  packageJson.dependencies.temporalio = temporalioVersion;
+  await writeFile(fileName, JSON.stringify(packageJson));
+}

package/src/helpers/is-online.ts

@@ -0,0 +1,44 @@
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/helpers/is-online.ts
+import { execSync } from 'child_process';
+import dns from 'dns';
+import { URL } from 'url';
+
+// Look for any proxy the user might have configured on their machine
+function getProxy(): string | undefined {
+  if (process.env.https_proxy) {
+    return process.env.https_proxy;
+  }
+
+  try {
+    const httpsProxy = execSync('npm config get https-proxy').toString().trim();
+    return httpsProxy !== 'null' ? httpsProxy : undefined;
+  } catch (e) {
+    return;
+  }
+}
+
+export function testIfThisComputerIsOnline(): Promise<boolean> {
+  return new Promise((resolve) => {
+    dns.lookup('github.com', (registryErr) => {
+      if (!registryErr) {
+        return resolve(true);
+      }
+
+      // If we can't reach the registry directly, see if the user has a proxy
+      // configured. If they do, see if the proxy is reachable.
+      const proxy = getProxy();
+      if (!proxy) {
+        return resolve(false);
+      }
+
+      const { hostname } = new URL(proxy);
+      if (!hostname) {
+        return resolve(false);
+      }
+
+      dns.lookup(hostname, (proxyErr) => {
+        resolve(proxyErr == null);
+      });
+    });
+  });
+}

package/src/helpers/is-writeable.ts

@@ -0,0 +1,17 @@
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/helpers/is-writeable.ts
+import fs from 'fs';
+
+import { getErrorCode } from './get-error-code.js';
+
+export async function isWriteable(directory: string): Promise<boolean> {
+  try {
+    await fs.promises.access(directory, (fs.constants || fs).W_OK);
+    return true;
+  } catch (error) {
+    if (getErrorCode(error) === 'EACCES') {
+      return false;
+    } else {
+      throw error;
+    }
+  }
+}

package/src/helpers/make-dir.ts

@@ -0,0 +1,6 @@
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/helpers/make-dir.ts
+import fs from 'fs';
+
+export async function makeDir(root: string, options = { recursive: true }): Promise<void> {
+  await fs.promises.mkdir(root, options);
+}

package/src/helpers/samples.ts

@@ -0,0 +1,136 @@
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/helpers/examples.ts
+import chalk from 'chalk';
+import got from 'got';
+import tar from 'tar';
+import { Stream } from 'stream';
+import { promisify } from 'util';
+import { rm, readdir } from 'fs/promises';
+import path from 'path';
+import { getErrorCode } from './get-error-code.js';
+
+const pipeline = promisify(Stream.pipeline);
+
+export type RepoInfo = {
+  username: string;
+  name: string;
+  branch: string;
+  filePath: string;
+};
+
+export async function isUrlOk(url: string): Promise<boolean> {
+  let res;
+  try {
+    res = await got.head(url);
+  } catch (e) {
+    return false;
+  }
+  return res.statusCode === 200;
+}
+
+// https://stackoverflow.com/a/3561711/627729
+function escapeRegex(s: string) {
+  // eslint-disable-next-line no-useless-escape
+  return s.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
+}
+
+export async function getRepoInfo(url: URL, samplePath?: string): Promise<RepoInfo> {
+  const [, username, name, t, _branch, ...file] = url.pathname.split('/');
+  const filePath = samplePath ? samplePath.replace(/^\//, '') : file.join('/');
+
+  // Support repos whose entire purpose is to be a Temporal sample, e.g.
+  // https://github.com/:username/:my-cool-temporal-sample-repo
+  if (t === undefined) {
+    const repo = `https://api.github.com/repos/${username}/${name}`;
+    let infoResponse;
+
+    try {
+      // https://github.com/sindresorhus/got/blob/main/documentation/3-streams.md#response-1
+      infoResponse = await got(repo);
+    } catch (error) {
+      throw new Error(`Unable to fetch ${repo}`);
+    }
+
+    if (infoResponse.statusCode !== 200) {
+      throw new Error(`Unable to fetch ${repo} — Code ${infoResponse.statusCode}: ${infoResponse.statusMessage}`);
+    }
+
+    const info = JSON.parse(infoResponse.body);
+    return { username, name, branch: info['default_branch'], filePath };
+  }
+
+  // If samplePath is available, the branch name takes the entire path
+  const branch = samplePath
+    ? `${_branch}/${file.join('/')}`.replace(new RegExp(`/${escapeRegex(filePath)}|/$`), '')
+    : _branch;
+
+  if (username && name && branch && t === 'tree') {
+    return { username, name, branch, filePath };
+  } else {
+    throw new Error(`Unable to parse URL: ${url} and sample path: ${samplePath}`);
+  }
+}
+
+export async function checkForPackageJson({ username, name, branch, filePath }: RepoInfo): Promise<void> {
+  const contentsUrl = `https://api.github.com/repos/${username}/${name}/contents`;
+  const packagePath = `${filePath ? `/${filePath}` : ''}/package.json`;
+
+  const fullUrl = contentsUrl + packagePath + `?ref=${branch}`;
+
+  if (!(await isUrlOk(fullUrl))) {
+    throw new Error(
+      `Could not locate a package.json at ${chalk.red(
+        `"${fullUrl}"`
+      )}.\nPlease check that the repository is a Temporal TypeScript SDK template and try again.`
+    );
+  }
+}
+
+export function hasSample(name: string): Promise<boolean> {
+  return isUrlOk(
+    `https://api.github.com/repos/temporalio/samples-typescript/contents/${encodeURIComponent(name)}/package.json`
+  );
+}
+
+export async function downloadAndExtractRepo(
+  root: string,
+  { username, name, branch, filePath }: RepoInfo
+): Promise<void> {
+  const archiveUrl = `https://codeload.github.com/${username}/${name}/tar.gz/${branch}`;
+  const archivePath = `${name}-${branch}${filePath ? `/${filePath}` : ''}`;
+
+  await pipeline(
+    got.stream(archiveUrl),
+    tar.extract({ cwd: root, strip: filePath ? filePath.split('/').length + 1 : 1 }, [archivePath])
+  );
+
+  const files = await readdir(root);
+  const pipelineFailed = files.length === 0;
+  if (pipelineFailed) {
+    console.error(
+      'We were unable to download and extract the provided project.\n',
+      `Archive URL: ${archiveUrl}\n`,
+      `Archive path: ${archivePath}\n`,
+      `Sometimes this is due to the repo name changing. If that's the case, try using the new repo URL.`
+    );
+    process.exit(1);
+  }
+}
+
+export async function downloadAndExtractSample(root: string, name: string): Promise<void> {
+  if (name === '__internal-testing-retry') {
+    throw new Error('This is an internal sample for testing the CLI.');
+  }
+
+  await pipeline(
+    got.stream('https://codeload.github.com/temporalio/samples-typescript/tar.gz/main'),
+    tar.extract({ cwd: root, strip: 2 }, [`samples-typescript-main/${name}`])
+  );
+
+  try {
+    await rm(path.join(root, `.npmrc`));
+  } catch (e) {
+    if (getErrorCode(e) !== 'ENOENT') {
+      throw e;
+    }
+  }
+}

package/src/helpers/strip-snip-comments.ts

@@ -0,0 +1,14 @@
+import glob from 'glob';
+import path from 'path';
+import { readFile, writeFile } from 'fs/promises';
+
+export async function stripSnipComments(root: string): Promise<void> {
+  const files = glob.sync('**/*.ts', { cwd: root });
+  await Promise.all(
+    files.map(async (file) => {
+      const filePath = path.join(root, file);
+      const fileString = await readFile(filePath, 'utf8');
+      await writeFile(filePath, fileString.replace(/ *\/\/ @@@SNIP.+\n/g, ''));
+    })
+  );
+}

package/src/helpers/subprocess.ts

@@ -0,0 +1,38 @@
+// https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
+import { ChildProcess, spawn as origSpawn, SpawnOptions } from 'child_process';
+
+export class ChildProcessError extends Error {
+  public readonly name = 'ChildProcessError';
+  public command?: string;
+  public args?: ReadonlyArray<string>;
+
+  constructor(message: string, public readonly code: number | null, public readonly signal: string | null) {
+    super(message);
+  }
+}
+
+export async function spawn(command: string, args?: ReadonlyArray<string>, options?: SpawnOptions): Promise<void> {
+  try {
+    // Workaround @types/node - avoid choosing overloads per options.stdio variants
+    await waitOnChild(options === undefined ? origSpawn(command, args) : origSpawn(command, args || [], options));
+  } catch (err) {
+    if (err instanceof ChildProcessError) {
+      err.command = command;
+      err.args = args;
+    }
+    throw err;
+  }
+}
+
+export async function waitOnChild(child: ChildProcess): Promise<void> {
+  return new Promise((resolve, reject) => {
+    child.on('exit', (code, signal) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new ChildProcessError('Process failed', code, signal));
+      }
+    });
+    child.on('error', reject);
+  });
+}

package/src/helpers/validate-pkg.ts

@@ -0,0 +1,17 @@
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/helpers/validate-pkg.ts
+import validateProjectName from 'validate-npm-package-name';
+
+export function validateNpmName(name: string): {
+  valid: boolean;
+  problems?: string[];
+} {
+  const nameValidation = validateProjectName(name);
+  if (nameValidation.validForNewPackages) {
+    return { valid: true };
+  }
+
+  return {
+    valid: false,
+    problems: [...(nameValidation.errors || []), ...(nameValidation.warnings || [])],
+  };
+}

package/src/index.ts

@@ -0,0 +1,217 @@
+// Modified from: https://github.com/vercel/next.js/blob/2425f4703c4c6164cecfdb6aa8f80046213f0cc6/packages/create-next-app/index.ts
+import chalk from 'chalk';
+import dedent from 'dedent';
+import { Command } from 'commander';
+import path from 'path';
+import prompts from 'prompts';
+import checkForUpdate from 'update-check';
+
+import { createApp } from './create-project.js';
+import { validateNpmName } from './helpers/validate-pkg.js';
+import { fetchSamples } from './helpers/fetch-samples.js';
+import packageJson from './pkg.js';
+
+const program = new Command(packageJson.name)
+  .version(packageJson.version, '-v, --version', 'Print the version and exit')
+  .arguments('[project-directory]')
+  .usage(`${chalk.green('[project-directory]')} [options]`)
+  .option(
+    '-s, --sample <name|github-url>',
+    dedent`
+  Which sample to bootstrap the project with. You can use the name of a sample
+  from https://github.com/temporalio/samples-typescript or use a GitHub URL. 
+  The URL can have a branch and/or subdirectory—for example:
+  https://github.com/temporalio/samples-typescript/tree/next/hello-world
+`
+  )
+  .option(
+    '--sample-path <path-to-sample>',
+    dedent`
+  In a rare case, your GitHub URL might contain a branch name with
+  a slash (e.g. bug/fix-1) and the path to the sample (e.g. foo/bar).
+  In this case, you must specify the path to the sample separately:
+  --sample-path foo/bar
+`
+  )
+  .option(
+    '-l, --list-samples',
+    dedent`
+  Print available sample projects and exit
+`
+  )
+  .option(
+    '--use-yarn',
+    dedent`
+  Use yarn instead of npm
+`
+  )
+  .option(
+    '--git-init',
+    dedent`
+  Initialize a git repository
+`
+  )
+  .option(
+    '--no-git-init',
+    dedent`
+  Skip git repository initialization
+`
+  )
+  .option(
+    '--temporalio-version <version>',
+    dedent`
+  Specify which version of the temporalio npm package to use
+`
+  )
+  .allowUnknownOption()
+  .parse(process.argv);
+
+interface Options {
+  useYarn?: boolean;
+  gitInit?: boolean;
+  listSamples?: boolean;
+  sample?: string;
+  samplePath?: string;
+  temporalioVersion?: string;
+}
+
+let opts: Options;
+
+async function start(): Promise<void> {
+  opts = program.opts();
+  if (opts.listSamples) {
+    const samples = await fetchSamples();
+    console.log(`Available samples:\n\n${samples.join('\n')}\n`);
+    return;
+  }
+
+  let projectPath = program.args[0];
+
+  if (typeof projectPath === 'string') {
+    projectPath = projectPath.trim();
+  }
+
+  if (!projectPath) {
+    const res = await prompts({
+      type: 'text',
+      name: 'path',
+      message: 'What is your project named?',
+      initial: 'my-temporal',
+      validate: (name) => {
+        const validation = validateNpmName(path.basename(path.resolve(name)));
+        if (validation.valid) {
+          return true;
+        }
+        return 'Invalid project name: ' + validation.problems?.[0];
+      },
+    });
+
+    if (typeof res.path === 'string') {
+      projectPath = res.path.trim();
+    }
+  }
+
+  if (!projectPath) {
+    console.error();
+    console.error('Please specify the project directory:');
+    console.error(`  ${chalk.cyan(program.name())} ${chalk.green('<project-directory>')}`);
+    console.error();
+    console.error('For example:');
+    console.error(`  ${chalk.cyan(program.name())} ${chalk.green('my-temporal-project')}`);
+    console.error();
+    console.error(`Run ${chalk.cyan(`${program.name()} --help`)} to see all options.`);
+    process.exit(1);
+  }
+
+  const resolvedProjectPath = path.resolve(projectPath);
+  const projectName = path.basename(resolvedProjectPath);
+
+  const { valid, problems } = validateNpmName(projectName);
+  if (!valid) {
+    console.error(
+      `Could not create a project called ${chalk.red(`"${projectName}"`)} because of npm naming restrictions:`
+    );
+
+    problems?.forEach((p) => console.error(`    ${chalk.red.bold('*')} ${p}`));
+    process.exit(1);
+  }
+
+  let sample = opts.sample;
+  if (!sample) {
+    const samples = await fetchSamples();
+    const choices = samples.map((sample) => ({ title: sample, value: sample }));
+
+    const res = await prompts({
+      type: 'select',
+      name: 'sample',
+      message: `Which sample would you like to use?`,
+      choices,
+      initial: samples.indexOf('hello-world'),
+    });
+
+    if (typeof res.sample === 'string') {
+      sample = res.sample;
+    }
+  }
+
+  if (!sample) {
+    console.error();
+    console.error('Please specify which sample:');
+    console.error(`  ${chalk.cyan(program.name())} --sample ${chalk.green('<name|github-url>')}`);
+    console.error();
+    console.error('For example:');
+    console.error(`  ${chalk.cyan(program.name())} --sample ${chalk.green('hello-world')}`);
+    console.error();
+    console.error(`Run ${chalk.cyan(`${program.name()} --help`)} to see all options.`);
+    process.exit(1);
+  }
+
+  await createApp({
+    appPath: resolvedProjectPath,
+    useYarn: !!opts.useYarn,
+    gitInit: opts.gitInit,
+    temporalioVersion: opts.temporalioVersion,
+    sample: sample.trim(),
+    samplePath: typeof opts.samplePath === 'string' ? opts.samplePath.trim() : undefined,
+  });
+}
+
+const update = checkForUpdate(packageJson).catch(() => null);
+
+async function notifyUpdate(): Promise<void> {
+  try {
+    const res = await update;
+    if (res?.latest) {
+      console.log();
+      console.log(chalk.yellow.bold('A new version of `@temporalio/create` is available!'));
+      console.log(
+        'You can update by running: ' +
+          chalk.cyan(opts.useYarn ? 'yarn global add @temporalio/create' : 'npm i -g @temporalio/create')
+      );
+      console.log();
+    }
+    process.exit();
+  } catch {
+    // ignore error
+  }
+}
+
+export function run(): void {
+  start()
+    .then(notifyUpdate)
+    .catch(async (reason) => {
+      console.log();
+      console.log('Aborting installation.');
+      if (reason.command) {
+        console.log(`  ${chalk.cyan(reason.command)} has failed.`);
+      } else {
+        console.log(chalk.red('Unexpected error. Please report it as a bug:'));
+        console.log(reason);
+      }
+      console.log();
+
+      await notifyUpdate();
+
+      process.exit(1);
+    });
+}

package/src/pkg.ts

@@ -0,0 +1,6 @@
+import { readFile } from 'fs/promises';
+import { URL } from 'url';
+
+const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+export default pkg as { name: string; version: string };