zero

Follow these steps to set up a standard local development environment for Zero:

1. Clone and Install Dependencies

   git clone https://github.com/Mail-0/Zero.git
   cd Zero
   pnpm install

2. Start the Database

   pnpm docker:db:up

3. Configure Environment Variables

   • Initialize your .env file: pnpm nizzy env
   • Sync environment variables and types: pnpm nizzy sync

4. Initialize Database Schema

   pnpm db:push

5. Start the Application

   pnpm dev

   The app will be available at http://localhost:3000.

# Clone the repository
git clone https://github.com/Mail-0/Zero.git
cd Zero

# Install dependencies
pnpm install

# Start database locally
pnpm docker:db:up

# Set Up Environment
pnpm nizzy env
pnpm nizzy sync

# Initialize the database
pnpm db:push

# Start the App
pnpm dev

To add a new script, follow these three steps:

1. Create the script file: Create a TypeScript file in apps/mail/scripts/ (or a subdirectory). Use the cmd-ts library to export a command object.
2. Register the command: Import your command and add it to the subcommands object in apps/mail/scripts/run.ts.
3. Run the script: Execute it via pnpm scripts <your-script-name> from the project root.

The system relies on cmd-ts for type-safe command-line argument handling.

// 1. Create apps/mail/scripts/my-script.ts
import { command, option, string as stringType } from 'cmd-ts';

export const myScriptCommand = command({
  name: 'my-script',
  description: 'Description of what my script does',
  args: {
    param1: option({
      type: stringType,
      long: 'param1',
      short: 'p',
      description: 'Description of param1',
    }),
  },
  handler: async (inputs) => {
    console.log(`Running my script with param1: ${inputs.param1}`);
  },
});

// 2. Register in apps/mail/scripts/run.ts
import { seedStyleCommand } from '@zero/mail/scripts/seed-style/seeder';
import { myScriptCommand } from '@zero/mail/scripts/my-script';
import { subcommands, run } from 'cmd-ts';

const app = subcommands({
  name: 'scripts',
  cmds: {
    'seed-style': seedStyleCommand,
    'my-script': myScriptCommand,
  },
});

await run(app, process.argv.slice(2));
process.exit(0);

Workflows are defined using the WorkflowDefinition type and registered with the WorkflowEngine instance. A workflow consists of a name, description, and an array of steps. Each step can include a condition (an async function that determines if the step should run) and an action (the logic to execute).

const autoDraftWorkflow: WorkflowDefinition = {
  name: 'auto-draft-generation',
  description: 'Automatically generates drafts for threads that require responses',
  steps: [
    {
      id: 'check-draft-eligibility',
      name: 'Check Draft Eligibility',
      description: 'Determines if a draft should be generated for this thread',
      enabled: true,
      condition: async (context) => {
        return shouldGenerateDraft(context.thread, context.foundConnection);
      },
      action: async (context) => {
        console.log('[WORKFLOW_ENGINE] Thread eligible for draft generation', context);
        return { eligible: true };
      },
    },
    // ... more steps
  ],
};

engine.registerWorkflow(autoDraftWorkflow);

Zero uses a utility called nizzy to manage environment variables. Run pnpm nizzy env to copy .env.example to .env and pre-fill variables. Use pnpm nizzy sync to ensure your environment variables and types are synchronized.

Required Service Configurations

Better Auth

Set BETTER_AUTH_SECRET to a random 32-character hex string (e.g., generated via openssl rand -hex 32).

Google OAuth (for Gmail integration)

1. Enable People API, Gmail API, and Google OAuth2 API in the Google Cloud Console.
2. Create OAuth 2.0 credentials (Web application).
3. Add authorized redirect URIs:
   • Dev: http://localhost:8787/api/auth/callback/google
   • Prod: https://your-production-url/api/auth/callback/google
4. Add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to .env.
5. Add your email as a Test User in the Google Cloud Console.

Autumn (for encryption)

Generate an Autumn Secret Key from the Autumn sandbox or production dashboard and add it to .env as AUTUMN_SECRET_KEY.

Twilio (for SMS integration)

Add the following to .env:

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER