@wirechunk/cli 0.0.1-rc.1

package/src/commands/dev/init-ext-db.ts

@@ -0,0 +1,263 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { DatabasePool } from 'slonik';
+import { createPool, sql } from 'slonik';
+import { z } from 'zod';
+import type { Env } from '../../env.js';
+import { requireCoreDbUrl } from '../../env.ts';
+import { isDuplicateDatabaseError } from '../../errors.ts';
+import type { WithGlobalOptions } from '../../global-options.js';
+import { dbPoolOptions, extensionDbName, requireExtensionIdOptionOrEnvVar } from '../../util.ts';
+
+const initSchemas = async ({
+  extensionDbName,
+  extensionRoleName,
+  coreDbUrl,
+  db,
+}: {
+  extensionDbName: string;
+  extensionRoleName: string;
+  coreDbUrl: URL;
+  db: DatabasePool;
+}) => {
+  await db.query(sql.unsafe`
+    create extension if not exists postgres_fdw
+  `);
+  await db.query(sql.unsafe`
+    create server if not exists wirechunk
+    foreign data wrapper postgres_fdw
+    options (
+      host ${sql.literalValue(coreDbUrl.hostname)},
+      port ${sql.literalValue(coreDbUrl.port)},
+      dbname ${sql.literalValue(coreDbUrl.pathname.slice(1))}
+    )
+  `);
+
+  const extRoleNameIdent = sql.identifier([extensionRoleName]);
+
+  await db.query(sql.unsafe`
+    create user mapping if not exists for ${extRoleNameIdent} server wirechunk
+    options (user ${sql.literalValue(extensionRoleName)}, password_required 'false')
+  `);
+  await db.query(sql.unsafe`
+    create foreign table if not exists "Users" (
+      "id" uuid not null,
+      "firstName" text not null,
+      "lastName" text not null,
+      "email" text not null,
+      "emailVerified" boolean not null,
+      "orgId" text,
+      "role" text,
+      "status" text not null,
+      "expiresAt" timestamptz,
+      "createdAt" timestamptz not null
+    ) server wirechunk options (schema_name 'public', table_name 'Users')
+  `);
+  await db.query(sql.unsafe`
+    create foreign table if not exists "Orgs" (
+      "id" text not null,
+      "name" text,
+      "primaryUserId" text,
+      "createdAt" timestamptz not null
+    ) server wirechunk options (schema_name 'public', table_name 'Orgs')
+  `);
+  await db.query(sql.unsafe`
+    create foreign table if not exists "Sites" (
+      "id" uuid not null,
+      "domain" text not null,
+      "orgId" text,
+      "name" text not null,
+      "createdAt" timestamptz not null
+    ) server wirechunk options (schema_name 'public', table_name 'Sites')
+  `);
+
+  // These are not the permissions granted to actual extension roles in production.
+  // Here we just want to simplify the development experience.
+  // At any moment, a developer may drop an extension's database and reinitialize it.
+  await db.query(sql.unsafe`
+    grant connect, create, temporary on database ${sql.identifier([extensionDbName])} to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    grant all on schema public to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    grant all on table "Orgs" to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    grant all on table "Sites" to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    grant all on table "Users" to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    alter default privileges grant all on schemas to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    alter default privileges grant all on types to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    alter default privileges grant all on tables to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    alter default privileges grant all on sequences to ${extRoleNameIdent}
+  `);
+  await db.query(sql.unsafe`
+    alter default privileges grant all on functions to ${extRoleNameIdent}
+  `);
+};
+
+const replaceDbName = (url: URL, dbName: string): URL => {
+  const urlObj = new URL(url.toString());
+  urlObj.pathname = `/${dbName}`;
+  return urlObj;
+};
+
+const extensionSelectSchema = z.object({
+  id: z.string(),
+  platformId: z.string(),
+});
+
+// Replace instances of a variable, or add a variable if needed, preserving other lines.
+const replaceEnvVar = (lines: string[], name: string, value: string): string[] => {
+  const newLines: string[] = [];
+  let hasName = false;
+  const namePattern = new RegExp(String.raw`^\s*${name}\s*=\s*`);
+  for (const line of lines) {
+    if (namePattern.test(line)) {
+      if (!hasName) {
+        newLines.push(`${name}=${value}`);
+        hasName = true;
+      }
+    } else {
+      newLines.push(line);
+    }
+  }
+  if (!hasName) {
+    newLines.push(`${name}=${value}`);
+  }
+  return newLines;
+};
+
+const applyExtensionPolicy = async ({
+  extRole,
+  table,
+  platformId,
+  db,
+}: {
+  extRole: string;
+  table: string;
+  platformId: string;
+  db: DatabasePool;
+}) => {
+  const policyNameIdent = sql.identifier([`${table}_ext_${extRole}_select`]);
+  const extRoleIdent = sql.identifier([extRole]);
+  const tableIdent = sql.identifier([table]);
+  await db.query(sql.unsafe`
+    drop policy if exists ${policyNameIdent} on ${tableIdent}
+  `);
+  await db.query(sql.unsafe`
+    create policy ${policyNameIdent} on ${tableIdent} as permissive
+    for select to ${extRoleIdent}
+    using ("platformId" = ${sql.literalValue(platformId)})
+  `);
+  await db.query(sql.unsafe`
+    grant select on ${tableIdent} to ${extRoleIdent}
+  `);
+};
+
+type InitExtDbOptions = {
+  extensionId?: string;
+  dbName?: string;
+};
+
+export const initExtDb = async (
+  opts: WithGlobalOptions<InitExtDbOptions>,
+  env: Env,
+): Promise<void> => {
+  const coreDbUrl = requireCoreDbUrl(env);
+  const extensionId = requireExtensionIdOptionOrEnvVar(opts, env);
+  const db = await createPool(coreDbUrl, dbPoolOptions(opts));
+
+  const extension = await db.maybeOne(sql.type(extensionSelectSchema)`
+    select "id", "platformId"
+    from "Extensions"
+    where "id" = ${extensionId}
+  `);
+  if (!extension) {
+    console.error(`Extension with ID ${extensionId} not found`);
+    process.exit(1);
+  }
+
+  const extDb = opts.dbName || extensionDbName(extensionId);
+
+  const coreDbUrlObject = new URL(coreDbUrl);
+  const extDbUrl = replaceDbName(coreDbUrlObject, extDb);
+  extDbUrl.pathname = `/${extDb}`;
+
+  const cwd = process.cwd();
+  const localEnvFilePath = opts.envMode
+    ? resolve(cwd, `./.env.${opts.envMode}.local`)
+    : resolve(cwd, './.env.local');
+  if (opts.verbose) {
+    console.log(`Loading ${localEnvFilePath} to update environment variables`);
+  }
+  if (existsSync(localEnvFilePath)) {
+    const localEnv = await readFile(localEnvFilePath, 'utf8');
+    const lines = replaceEnvVar(localEnv.split('\n'), 'DATABASE_URL', extDbUrl.toString());
+    await writeFile(localEnvFilePath, lines.join('\n'));
+  } else {
+    await writeFile(localEnvFilePath, `DATABASE_URL=${extDbUrl.toString()}\n`);
+  }
+
+  try {
+    await db.query(sql.unsafe`
+      create database ${sql.identifier([extDb])}
+    `);
+  } catch (err) {
+    if (!isDuplicateDatabaseError(err)) {
+      console.error('Failed to create a database:', err);
+      process.exit(1);
+    }
+  }
+
+  const extRole = `ext_${extension.id}`;
+
+  const extRoleIdent = sql.identifier([extRole]);
+  await db.query(sql.unsafe`
+    do $$
+    begin
+      if not exists (
+        select 1 from pg_roles where rolname = ${sql.literalValue(extRole)}
+      ) then
+        create role ${extRoleIdent} login noinherit;
+      end if;
+    end; $$
+  `);
+
+  await applyExtensionPolicy({
+    extRole,
+    table: 'Orgs',
+    platformId: extension.platformId,
+    db,
+  });
+  await applyExtensionPolicy({
+    extRole,
+    table: 'Sites',
+    platformId: extension.platformId,
+    db,
+  });
+  await applyExtensionPolicy({
+    extRole,
+    table: 'Users',
+    platformId: extension.platformId,
+    db,
+  });
+
+  await initSchemas({
+    extensionDbName: extDb,
+    extensionRoleName: extRole,
+    coreDbUrl: coreDbUrlObject,
+    db: await createPool(extDbUrl.toString(), dbPoolOptions(opts)),
+  });
+};

package/src/commands/edit-admin.ts

@@ -0,0 +1,69 @@
+import { createPool, sql, UniqueIntegrityConstraintViolationError } from 'slonik';
+import { z } from 'zod';
+import type { Env } from '../env.ts';
+import { requireCoreDbUrl } from '../env.ts';
+import { detailedUniqueIntegrityConstraintViolationError } from '../errors.ts';
+import type { WithGlobalOptions } from '../global-options.ts';
+
+const findUserSchema = z.object({
+  id: z.string(),
+  platformId: z.string(),
+});
+
+type EditAdminOptions = {
+  platformId: string;
+  userId: string;
+  owner?: boolean;
+  revokeAllPermissions?: boolean;
+};
+
+export const editAdmin = async (
+  opts: WithGlobalOptions<EditAdminOptions>,
+  env: Env,
+): Promise<void> => {
+  const db = await createPool(requireCoreDbUrl(env));
+  const { platformId, userId, owner, revokeAllPermissions } = opts;
+
+  if (owner && revokeAllPermissions) {
+    console.error(
+      'Cannot set a user as a platform owner and revoke all permissions at the same time',
+    );
+    process.exit(1);
+  }
+
+  try {
+    await db.transaction(async (db) => {
+      const platformAdmin = await db.maybeOne(
+        sql.type(
+          findUserSchema,
+        )`select "id" from "PlatformAdmins" where "platformId" = ${platformId} and "userId" = ${userId}`,
+      );
+      if (!platformAdmin) {
+        const user = await db.maybeOne(
+          sql.type(findUserSchema)`select "id" from "Users" where "id" = ${userId}`,
+        );
+        if (!user) {
+          throw new Error(`User with ID ${userId} not found`);
+        }
+      }
+
+      // TODO
+
+      // if (owner) {
+      //   await grantAllUserPlatformPermissions({ userId: id, platformId: user.platformId }, db);
+      //   console.log('Set user as a platform admin');
+      // }
+      // if (revokeAllPermissions) {
+      //   await revokeAllUserPlatformPermissions({ userId: id }, db);
+      //   console.log('Revoked all platform permissions of user');
+      // }
+    });
+  } catch (e) {
+    if (e instanceof UniqueIntegrityConstraintViolationError) {
+      console.error(detailedUniqueIntegrityConstraintViolationError(e));
+      process.exit(1);
+    }
+    console.error(e);
+    process.exit(1);
+  }
+};

package/src/env.ts

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import process from 'node:process';
+import { parseEnv as parseEnvContents } from 'node:util';
+import { isLocalhost } from '@wirechunk/lib/localhost.ts';
+
+export type Env = Record<string, string> & {
+  CORE_DATABASE_URL?: string;
+  // A URL to the server root, like https://wirechunk.com or http://admin.localhost:8080
+  CORE_SERVER_URL: string;
+  WIRECHUNK_API_TOKEN?: string;
+};
+
+// A .env file is required only if the required environment variables are not already set.
+const envFilePath = '.env';
+const envLocalFilePath = '.env.local';
+
+const hasEnvFile = existsSync(envFilePath);
+
+export const requireApiToken = (env: Env): string => {
+  if (!env.WIRECHUNK_API_TOKEN) {
+    console.error(
+      'Missing API token for authentication. Provide a WIRECHUNK_API_TOKEN environment variable.',
+    );
+    process.exit(1);
+  }
+  return env.WIRECHUNK_API_TOKEN;
+};
+
+export const requireCoreDbUrl = (env: Env): string => {
+  if (!env.CORE_DATABASE_URL) {
+    if (hasEnvFile) {
+      console.error('Missing CORE_DATABASE_URL in environment');
+    } else {
+      console.error(`Missing CORE_DATABASE_URL in environment, no ${envFilePath} file found`);
+    }
+    process.exit(1);
+  }
+  return env.CORE_DATABASE_URL;
+};
+
+const coreServerUrlFromEnv = (env: Record<string, string>): string => {
+  const url = env.CORE_SERVER_URL;
+  if (url) {
+    return url.endsWith('/api') ? url.substring(0, url.length - 4) : url;
+  }
+  const adminDomain = env.ADMIN_DOMAIN;
+  if (adminDomain) {
+    return isLocalhost(adminDomain) ? `http://${adminDomain}` : `https://${adminDomain}`;
+  }
+  return 'https://wirechunk.com';
+};
+
+export const parseEnv = async (envMode: string | undefined): Promise<Env> => {
+  const env: Record<string, string> = {};
+
+  if (hasEnvFile) {
+    const envFileRaw = await readFile(envFilePath, 'utf8');
+    Object.assign(env, parseEnvContents(envFileRaw));
+  }
+  if (envMode) {
+    const modeFilePath = `.env.${envMode}`;
+    if (existsSync(modeFilePath)) {
+      const modeFileRaw = await readFile(modeFilePath, 'utf8');
+      Object.assign(env, parseEnvContents(modeFileRaw));
+    }
+  }
+  if (existsSync(envLocalFilePath)) {
+    const envLocalFileRaw = await readFile(envLocalFilePath, 'utf8');
+    Object.assign(env, parseEnvContents(envLocalFileRaw));
+  }
+  if (envMode) {
+    const modeLocalFilePath = `.env.${envMode}.local`;
+    if (existsSync(modeLocalFilePath)) {
+      const modeLocalFileRaw = await readFile(modeLocalFilePath, 'utf8');
+      Object.assign(env, parseEnvContents(modeLocalFileRaw));
+    }
+  }
+  Object.assign(env, process.env);
+
+  return {
+    ...env,
+    CORE_SERVER_URL: coreServerUrlFromEnv(env),
+  };
+};

package/src/errors.ts

@@ -0,0 +1,30 @@
+import type { UniqueIntegrityConstraintViolationError } from 'slonik';
+
+export const detailedUniqueIntegrityConstraintViolationError = (
+  error: UniqueIntegrityConstraintViolationError,
+): string => {
+  // The default error message is not very helpful, so we provide a more specific one.
+  const message =
+    error.message === 'Query violates a unique integrity constraint.'
+      ? `A database uniqueness constraint was violated when inserting or updating`
+      : error.message;
+  const details: string[] = [];
+  if (error.table) {
+    details.push(`table "${error.table}"`);
+  }
+  if (error.column) {
+    details.push(`column "${error.column}"`);
+  }
+  if (error.constraint) {
+    details.push(`constraint "${error.constraint}"`);
+  }
+  if (details.length) {
+    return `${message} (${details.join(', ')})`;
+  }
+  return message;
+};
+
+// Returns true if error is an object with a code property that signifies there is a duplicate database.
+// Note the expected shape comes from the 'pg' library.
+export const isDuplicateDatabaseError = (error: unknown): boolean =>
+  !!error && typeof error === 'object' && 'code' in error && error.code === '42P04';

package/src/fetch.ts

@@ -0,0 +1,32 @@
+import { lookup } from 'node:dns';
+import { isLocalhost } from '@wirechunk/lib/localhost.ts';
+import * as undici from 'undici';
+
+// To allow easily accessing localhost subdomains without needing to override /etc/hosts, this function provides a DNS resolver
+// that resolves to 127.0.0.1 for localhost domains.
+export const fetchWithLocal = (
+  url: string,
+  init: RequestInit & undici.RequestInit,
+): Promise<Response | undici.Response> => {
+  const { host } = new URL(url);
+  if (isLocalhost(host)) {
+    return undici.fetch(url, {
+      ...init,
+      dispatcher: new undici.Agent({
+        connect: {
+          lookup: (hostname, options, callback) => {
+            if (isLocalhost(hostname)) {
+              callback(null, [
+                { address: '127.0.0.1', family: 4 },
+                { address: '::1', family: 6 },
+              ]);
+              return;
+            }
+            lookup(hostname, options, callback);
+          },
+        },
+      }),
+    });
+  }
+  return fetch(url, init);
+};

package/src/global-options.ts

@@ -0,0 +1,6 @@
+export type GlobalOptions = {
+  verbose?: boolean;
+  envMode?: string;
+};
+
+export type WithGlobalOptions<T> = T & GlobalOptions;

package/src/main.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import type { OptionValues } from '@commander-js/extra-typings';
+import { Command, Option } from '@commander-js/extra-typings';
+import chalk from 'chalk';
+import { bootstrap } from './commands/bootstrap.ts';
+import { createExtensionVersion } from './commands/create-extension-version.ts';
+import { createUser } from './commands/create-user.ts';
+import { initExtDb } from './commands/dev/init-ext-db.ts';
+import { editAdmin } from './commands/edit-admin.ts';
+import type { Env } from './env.ts';
+import { parseEnv } from './env.ts';
+import type { WithGlobalOptions } from './global-options.ts';
+
+const program = new Command()
+  .name('wirechunk')
+  .option('--verbose', 'output debug logging')
+  .option(
+    '--env-mode <mode>',
+    'the mode to use for finding .env files to load environment variables, such as "test" to load .env, .env.test, .env.local, and .env.test.local',
+  ).description(`The official Wirechunk CLI
+
+By default, environment variables are loaded from the .env file in the current working directory,
+then the .env.local file, and then from the environment. Variables from the environment have the
+highest precedence.
+
+Environment variables used by some commands:
+  CORE_SERVER_URL (the core admin server URL for commands using the API)
+  CORE_DATABASE_URL (the core database URL for commands requiring direct database access)`);
+
+const withOptionsAndEnv =
+  <Args extends string[], Options extends OptionValues>(
+    action: (options: WithGlobalOptions<Options>, env: Env) => Promise<void> | void,
+  ) =>
+  async (options: Options, cmd: Command<Args, Options>) => {
+    const mergedOptions = { ...program.opts(), ...options };
+    if (mergedOptions.verbose) {
+      console.log(`Running ${chalk.green.bold(cmd.name())}`);
+    }
+    const env = await parseEnv(mergedOptions.envMode);
+    return action(mergedOptions, env);
+  };
+
+program
+  .command('bootstrap')
+  .description('create a platform')
+  .requiredOption('--name <string>', 'the name of the platform')
+  .option('--handle <string>', 'the handle of the platform (used by the admin site)')
+  .requiredOption(
+    '--admin-site-domain <string>',
+    'the domain of the platform admin site (dashboard)',
+  )
+  .option(
+    '--email-send-from <string>',
+    'the email address from which to send emails, defaults to "site@<admin-site-domain>',
+  )
+  .action(withOptionsAndEnv(bootstrap));
+
+program
+  .command('create-extension-version')
+  .description('create an extension version')
+  .option(
+    '--extension-id <string>',
+    'the ID of the extension, can be set with an EXTENSION_ID environment variable instead',
+  )
+  .requiredOption('--version-name <string>', 'the name of the version')
+  .action(withOptionsAndEnv(createExtensionVersion));
+
+program
+  .command('create-user')
+  .description('create a user')
+  .requiredOption('--email <string>', 'the email address of the user')
+  .requiredOption('--password <string>', 'the password of the user')
+  .requiredOption('--first-name <string>', 'the first name of the user')
+  .requiredOption('--last-name <string>', 'the last name of the user')
+  .option(
+    '--org-id <string>',
+    'the ID of the org to which the user belongs, defaults to creating a new org if not specified',
+  )
+  .option(
+    '--platform-id <string>',
+    'the ID of the platform ID to which the users will be added, used only if org ID is not specified',
+  )
+  .addOption(
+    new Option('--role <string>', 'the role the user will have').default('OrganizationOwner'),
+  )
+  .option('--email-verified', 'mark the email address as already verified by the user', false)
+  .option('--pending', 'create the user in a pending state', false)
+  .action(withOptionsAndEnv(createUser));
+
+// TODO: create-admin
+
+const dev = program.command('dev').description('extension development commands');
+
+dev
+  .command('init-ext-db')
+  .description('initialize a development database for an extension')
+  .option(
+    '--extension-id <string>',
+    'the ID of the extension, can be set with an EXTENSION_ID environment variable instead',
+  )
+  .option('--db-name <string>', 'a custom name for the database, applicable only for testing')
+  .action(withOptionsAndEnv(initExtDb));
+
+program
+  .command('edit-admin')
+  .description('edit a platform admin user')
+  .requiredOption('--platform-id <string>', 'the ID of the platform to edit')
+  .requiredOption('--user-id <string>', 'the ID of the admin user to edit')
+  .option('--owner', 'grants the user full permission to manage everything on the platform')
+  .option('--revoke-all-permissions', 'revokes all permission of the user on their platform')
+  .action(withOptionsAndEnv(editAdmin));
+
+await program.parseAsync();

package/src/users/permissions.ts

@@ -0,0 +1,39 @@
+import { Permission } from '@wirechunk/lib/graphql-api-enums.ts';
+import type { CommonQueryMethods } from 'slonik';
+import { sql } from 'slonik';
+import { voidSelectSchema } from '../util.ts';
+
+export const allPermissions = Object.values(Permission);
+
+export const revokeAllUserPlatformPermissions = async (
+  {
+    userId,
+  }: {
+    userId: string;
+  },
+  db: CommonQueryMethods,
+): Promise<void> => {
+  await db.query(
+    sql.type(voidSelectSchema)`delete from "UserPlatformPermissions" where "userId" = ${userId}`,
+  );
+};
+
+export const grantAllUserPlatformPermissions = async (
+  {
+    userId,
+    platformId,
+  }: {
+    userId: string;
+    platformId: string;
+  },
+  db: CommonQueryMethods,
+): Promise<void> => {
+  await db.query(
+    sql.type(
+      voidSelectSchema,
+    )`insert into "UserPlatformPermissions" ("userId", "platformId", "permission") values ${sql.join(
+      allPermissions.map((permission) => sql.fragment`(${userId}, ${platformId}, ${permission})`),
+      sql.fragment`,`,
+    )} on conflict on constraint "UserPlatformPermissions_pkey" do nothing`,
+  );
+};

package/src/util.ts

@@ -0,0 +1,29 @@
+import type { ClientConfigurationInput } from 'slonik/src/types.js';
+import { createQueryLoggingInterceptor } from 'slonik-interceptor-query-logging';
+import { z } from 'zod';
+import type { Env } from './env.ts';
+import type { GlobalOptions } from './global-options.ts';
+
+// Returns the name to use for an extension's database in development mode.
+export const extensionDbName = (id: string): string => `ext_${id}`;
+
+export const voidSelectSchema = z.object({});
+
+export const requireExtensionIdOptionOrEnvVar = (
+  options: { extensionId?: string },
+  env: Env,
+): string => {
+  const extensionId = options.extensionId || env.EXTENSION_ID;
+  if (!extensionId) {
+    console.error(
+      'Missing an extension ID, must be specified either as the --extension-id argument or the EXTENSION_ID environment variable',
+    );
+    process.exit(1);
+  }
+  return extensionId;
+};
+
+// Returns the value for the interceptors property to use on a Slonik ClientConfigurationInput.
+// Note that you still need to set a ROARR_LOG=true environment variable to enable logging.
+export const dbPoolOptions = (opts: GlobalOptions): ClientConfigurationInput =>
+  opts.verbose ? { interceptors: [createQueryLoggingInterceptor({ logValues: true })] } : {};

package/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["**/*.test.ts", "tests/**"],
+  "compilerOptions": {
+    "outDir": "build",
+    "noEmit": false,
+    "skipLibCheck": true,
+    "removeComments": true
+  }
+}