@temporalio/create 0.23.0 → 1.0.0

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.test.ts

@@ -0,0 +1,46 @@
+import test from 'ava';
+import dedent from 'dedent';
+import { readFile, rm, writeFile } from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { v4 as uuid } from 'uuid';
+import { replaceSdkVersion } from './install.js';
+import { makeDir } from './make-dir.js';
+
+test('replaceSdkVersion according to configured level', async (t) => {
+  console.log('debug windows');
+  // console.log('import.meta.url', import.meta.url);
+  // console.log('URL', new URL('../../test', import.meta.url));
+  const tempDir = path.join(os.tmpdir(), uuid());
+  console.log('tempDir:', tempDir);
+  await makeDir(tempDir);
+
+  // const { pathname: tempDir } = new URL('../../test', import.meta.url);
+  const packageJson = path.join(tempDir, 'package.json');
+  console.log('packageJson', packageJson);
+  await writeFile(
+    packageJson,
+    dedent`
+  {
+    "name": "test-create-project",
+    "version": "0.1.0",
+    "private": true,
+    "dependencies": {
+      "@temporalio/activity": "^1.0.0",
+      "@temporalio/client": "^1.0.0",
+      "@temporalio/worker": "^1.0.0",
+      "@temporalio/workflow": "^1.0.0",
+      "nanoid": "3.x"
+    }
+  }
+  `
+  );
+
+  await replaceSdkVersion({ root: tempDir, sdkVersion: 'foo' });
+  const replaced = JSON.parse(await readFile(packageJson, 'utf8'));
+  t.is(replaced.dependencies['@temporalio/activity'], 'foo');
+  t.is(replaced.dependencies['@temporalio/client'], 'foo');
+  t.is(replaced.dependencies.nanoid, '3.x');
+
+  await rm(tempDir, { recursive: true });
+});

package/src/helpers/install.ts

@@ -0,0 +1,66 @@
+// 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;
+  sdkVersion?: 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 replaceSdkVersion({ root, sdkVersion }: InstallArgs): Promise<void> {
+  const fileName = `${root}/package.json`;
+
+  const packageJson = JSON.parse(await readFile(fileName, 'utf8'));
+  for (const packageName in packageJson.dependencies) {
+    if (packageName.startsWith('@temporalio/')) {
+      packageJson.dependencies[packageName] = sdkVersion;
+    }
+  }
+  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,142 @@
+// 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}`;
+
+  try {
+    const response = await got.head(fullUrl);
+    if (response.statusCode !== 200) {
+      throw response;
+    }
+  } catch (e) {
+    console.error(e);
+    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(
+    '--sdk-version <version>',
+    dedent`
+  Specify which version of the @temporalio/* npm packages to use
+`
+  )
+  .allowUnknownOption()
+  .parse(process.argv);
+
+interface Options {
+  useYarn?: boolean;
+  gitInit?: boolean;
+  listSamples?: boolean;
+  sample?: string;
+  samplePath?: string;
+  sdkVersion?: 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,
+    sdkVersion: opts.sdkVersion,
+    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);
+    });
+}