@project-ajax/create 0.0.12 → 0.0.14

package/README.md

@@ -4,6 +4,21 @@ A CLI for creating new Project Ajax workers projects.
 
 ## Usage
 
+### Interactive Mode
+
 ```bash
 npm init @project-ajax
 ```
+
+### Non-Interactive Mode
+
+For CI environments or scripted usage:
+
+```bash
+npm init @project-ajax -- --directory my-worker --project my-worker
+```
+
+#### Options
+
+- `--directory`, `-d` - Path to the new worker project (default: `.`)
+- `--project`, `-p` - Project name (default: `my-worker`)

package/dist/index.js

@@ -2,13 +2,14 @@
 
 // src/index.ts
 import fs from "fs";
-import os from "os";
 import path from "path";
+import { fileURLToPath } from "url";
 import { parseArgs } from "util";
+import * as prompts from "@inquirer/prompts";
 import chalk from "chalk";
-import { execa } from "execa";
 import ora from "ora";
-import prompts from "prompts";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
 run().then(() => {
   process.exit(0);
 }).catch((err) => {
@@ -30,43 +31,35 @@ async function run() {
       }
     }
   });
-  const promptQuestions = [];
-  if (!values.directory) {
-    promptQuestions.push({
-      type: "text",
-      name: "directoryName",
+  let directoryName = values.directory;
+  let projectName = values.project;
+  if (!directoryName) {
+    directoryName = await safePrompt({
       message: "Path to the new worker project:",
-      initial: "."
+      default: ".",
+      required: true,
+      noTTY: "Provide the path to the new project with --directory"
     });
   }
-  if (!values.project) {
-    promptQuestions.push({
-      type: "text",
-      name: "projectName",
+  if (!projectName) {
+    projectName = await safePrompt({
       message: "Project name:",
-      initial: "my-worker"
+      default: "my-worker",
+      required: true,
+      noTTY: "Provide the project name with --project"
     });
   }
-  let answers;
-  if (promptQuestions.length > 0) {
-    answers = await prompts(promptQuestions);
-  }
-  const directoryName = values.directory ?? answers?.directoryName;
-  const projectName = values.project ?? answers?.projectName;
   if (!directoryName || !projectName) {
     console.log(chalk.red("Cancelled."));
     process.exit(1);
   }
   const spinner = ora("Setting up template...").start();
-  let tempDir = null;
   try {
-    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "project-ajax-"));
-    spinner.text = "Fetching template from repository...";
-    await pullCode(tempDir);
     spinner.text = "Preparing destination...";
     const destPath = prepareDestination(directoryName);
     spinner.text = "Copying template files...";
-    copyTemplate(tempDir, destPath);
+    const templatePath = getTemplatePath();
+    copyTemplate(templatePath, destPath);
     spinner.text = "Customizing package.json...";
     customizePackageJson(destPath, projectName);
     spinner.succeed(chalk.green("Worker project created successfully!"));
@@ -77,46 +70,11 @@ async function run() {
       chalk.red(`
 ${err instanceof Error ? err.message : String(err)}`)
     );
-    if (err instanceof Error && (err.message.includes("Permission denied") || err.message.includes("publickey"))) {
-      console.log(
-        chalk.yellow("\n\u26A0\uFE0F  SSH authentication failed. Make sure you have:")
-      );
-      console.log("  1. SSH keys set up with GitHub");
-      console.log("  2. Added your SSH key to your GitHub account");
-      console.log(
-        "  3. See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh"
-      );
-    }
     process.exit(1);
-  } finally {
-    if (tempDir) {
-      try {
-        fs.rmSync(tempDir, { recursive: true, force: true });
-      } catch {
-      }
-    }
   }
 }
-async function pullCode(tempDir) {
-  await execa("git", ["init"], { cwd: tempDir });
-  await execa(
-    "git",
-    ["remote", "add", "origin", "git@github.com:makenotion/project-ajax.git"],
-    { cwd: tempDir }
-  );
-  await execa("git", ["config", "core.sparseCheckout", "true"], {
-    cwd: tempDir
-  });
-  const sparseCheckoutPath = path.join(
-    tempDir,
-    ".git",
-    "info",
-    "sparse-checkout"
-  );
-  fs.writeFileSync(sparseCheckoutPath, "packages/template/*\n");
-  await execa("git", ["pull", "--depth=1", "origin", "main"], {
-    cwd: tempDir
-  });
+function getTemplatePath() {
+  return path.resolve(__dirname, "..", "template");
 }
 function prepareDestination(repoName) {
   const destPath = repoName === "." ? process.cwd() : path.resolve(process.cwd(), repoName);
@@ -132,8 +90,12 @@ function prepareDestination(repoName) {
   }
   return destPath;
 }
-function copyTemplate(tempDir, destPath) {
-  const templatePath = path.join(tempDir, "packages", "template");
+function copyTemplate(templatePath, destPath) {
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(
+      `Template directory not found at ${templatePath}. This is likely a packaging issue.`
+    );
+  }
   const templateFiles = fs.readdirSync(templatePath);
   for (const file of templateFiles) {
     const srcPath = path.join(templatePath, file);
@@ -169,3 +131,17 @@ function printNextSteps(directoryName) {
     `);
   }
 }
+function safePrompt(config) {
+  if (!process.stdin.isTTY) {
+    console.error(chalk.red(config.noTTY));
+    process.exit(1);
+  }
+  return prompts.input(config).catch((err) => {
+    if (err instanceof Error && err.name === "ExitPromptError") {
+      console.log(chalk.red("\u{1F44B} Goodbye!"));
+      process.exit(1);
+    } else {
+      throw err;
+    }
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/create",
-	"version": "0.0.12",
+	"version": "0.0.14",
 	"description": "Initialize a new Notion Project Ajax extensions repo.",
 	"bin": {
 		"create-ajax": "dist/index.js"
@@ -22,17 +22,16 @@
 		"access": "public"
 	},
 	"files": [
-		"dist/"
+		"dist/",
+		"template/"
 	],
 	"dependencies": {
+		"@inquirer/prompts": "^8.0.1",
 		"chalk": "^5.3.0",
-		"execa": "^8.0.0",
-		"ora": "^8.0.1",
-		"prompts": "^2.4.2"
+		"ora": "^8.0.1"
 	},
 	"devDependencies": {
 		"@types/node": "^22.19.0",
-		"@types/prompts": "^2.4.9",
 		"tsup": "^8.5.0",
 		"typescript": "^5.9.3"
 	}

package/template/README.md

@@ -0,0 +1,700 @@
+# README
+
+Use this repo to write extensions to enhance Notion. With Notion extensions, you can write JavaScript that syncs data into Notion collections, adds new slash-commands, or provides new actions to Custom Agents.
+
+## Prerequisites
+
+### Node
+
+You need Node >= 22, npm >= 10 installed. (The repo will warn you if you don't.)
+
+### Access to the feature
+
+This feature is behind a feature flag (i.e. Statsig gate) in Notion.
+
+See a `#proj-ajax` team member to gain access.
+
+## Quickstart
+
+In this Quickstart, you’ll:
+
+- Clone this extensions template
+- Publish example extensions to your Notion workspace
+
+### 1. Create worker project from template
+
+Use `npm init` to setup a project template:
+
+```
+npm init @project-ajax
+```
+
+When prompted, enter a path to the new project, e.g. `my-extensions`.
+
+### 2. Install packages and connect the repo to Notion
+
+Install packages:
+
+```
+# or whatever you chose for the pathname
+cd my-extensions && npm i
+```
+
+Now, run `npx workers` to verify the tool has installed:
+
+```
+npx workers
+
+USAGE
+  workers auth login|show|logout ...
+  workers deploy [--config value] [--debug]
+  workers secrets set|list|rm ...
+  workers --help
+  workers --version
+
+A CLI for the Project Ajax platform
+
+[ ... ]
+```
+
+Then, connect the repo to Notion to publish the example extensions to your Notion workspace:
+
+```
+# Connect to Notion Prod
+npx workers auth login
+# Connect to Notion Dev
+npx workers auth login --env=dev
+```
+
+This command will open a new page with a command that includes a token. Run that command locally. It will look like this:
+
+```
+# example
+npx workers auth login v1.user.wAFygwEZ-[...] --env=dev
+```
+
+> **Note**
+>
+> If the command opens a page that 404s, you likely do not have Statsig access to extensions. See a #proj-virtual-databases team member for access.
+
+### 3. Deploy
+
+Run the following command to deploy this repo's example extensions to your Notion workspace:
+
+```
+npx workers deploy
+
+Deploying worker...
+Updating worker...
+Building worker bundle...
+Uploading bundle...
+Fetching and saving worker capabilities...
+✓ Successfully deployed worker
+```
+
+### 4. Try out the sample worker
+
+The sample worker installs three capabilities:
+
+- [Synced database](#try-the-synced-database)
+- [Agent tool](#try-the-agent-tool)
+- [Slash command](#try-the-slash-command)
+
+#### Try the synced database
+
+After deploying, the sync runs automatically and creates a database in your private pages - you can find it in your sidebar or by searching "Sample Tasks".
+
+Alternatively, run the sync via the CLI to get the URL:
+
+```
+npx workers exec tasksSync
+```
+
+When the command completes you will see the URL for the `Sample Tasks` database.
+
+#### Try the agent tool
+
+To exercise the sample agent tool, first navigate to a new or existing custom agent in Notion.
+
+On the settings tab, choose Add connection:
+
+<img src="./docs/custom-agent-add-connection.png" style="width:400px">
+
+Scroll down to find the installed worker which has the name used when you deployed the worker. Click Add.
+
+<img src="./docs/custom-agent-select-worker.png" style="width:400px">
+
+Save settings, then navigate to the **chat** tab. Our sample tool call allows for searching tasks by id or keyword - try asking Agent to find tasks related to "Ajax" or "worker".
+
+#### Try the slash command
+
+In your Notion workspace, **first refresh**. Then, type forward-slash (`/insert`) and select the "Insert Sample Task" capability:
+
+<img src="./docs/insert-sample-task.png" style="width:300px" />
+
+In the search field that appears, type `ajax` to preview matching sample tasks:
+
+<img src="./docs/select-ajax.png" style="width:400px" />
+
+After execution, the function will insert blocks into the page:
+
+<img src="./docs/inserted-blocks.png" style="width:400px" />
+
+## How-to build your own
+
+### 1. Create repo from template
+
+If you haven't already, use the GitHub CLI to create a new repo from this template:
+
+```
+gh repo create notion-extensions -p makenotion/project-ajax-template --private
+git clone git@github.com:[YOUR-USER]/notion-extensions my-extensions
+```
+
+Alternatively, you can click "Create from template" on the repo's page [on GitHub](https://github.com/makenotion/project-ajax-template).
+
+### 2. Install packages and connect the repo to Notion
+
+Install packages:
+
+```
+cd my-extensions && npm i
+```
+
+Then, connect the repo to Notion to publish the example extensions to your Notion workspace:
+
+```
+# Connect to Notion Prod
+npx workers auth login
+# Connect to Notion Dev
+npx workers auth login --env=dev
+```
+
+This command will open a new page with a command that includes a token. Run that command locally.
+
+### 3. Write your extension(s)
+
+You can write three types of extensions: **slash commands**, **syncs**, and **tools**.
+
+#### Writing a slash command function
+
+[Slash commands](#slash-commands) add custom `/` commands to your Notion workspace.
+
+Basic structure:
+
+```typescript
+import { slashCommand } from "@project-ajax/sdk/slashCommand";
+
+export const myCommand = slashCommand({
+  // Title in slash command menu
+  menuTitle: "My Command",
+  // Description in slash command menu
+  menuDescription: "Description shown in menu",
+  search: {
+    // Placeholder shown in search bar
+    placeholder: "Search...",
+    // Debounce when user types into the search bar, in milliseconds
+    debounce: 300,
+  },
+  // Called when the user enters a search query. Return results to show to user in search menu.
+  executeSearch: async (query: string) => {
+    // Return search results
+    return { items: [{ id: "1", title: "Result", description: "..." }] };
+  },
+  // Called when the user has selected a search item from the search menu.
+  executeSelect: async (id: string) => {
+    // Return Notion blocks to insert
+    return [
+      /* array of blocks */
+    ];
+  },
+});
+```
+
+#### Writing a sync function
+
+[Sync functions](#sync) populate Notion collections with data from external sources.
+
+Basic structure:
+
+```typescript
+import { sync } from "@project-ajax/sdk/sync";
+import * as Schema from "@project-ajax/sdk/schema";
+import * as Builder from "@project-ajax/sdk/builder";
+
+export const mySync = sync({
+  // Which field to use in each object as the primary key. Must be unique.
+  primaryKeyProperty: "ID",
+  // The schema of the collection to create in Notion.
+  schema: {
+    // Name of the collection to create in Notion.
+    dataSourceTitle: "My Data",
+    properties: {
+      // See `Schema` for the full list of possible column types.
+      Title: Schema.title(),
+      ID: Schema.richText(),
+    },
+  },
+  execute: async () => {
+    // Fetch and return data
+    return [
+      // Each object must match the shape of `properties` above.
+      {
+        key: "1",
+        properties: {
+          Title: Builder.title("Item 1"),
+          ID: Builder.richText("1"),
+        },
+      },
+    ];
+  },
+});
+```
+
+#### Writing a tool for custom agents
+
+[Tools](#tools) provide custom actions that can be invoked by custom agents in your Notion workspace.
+
+Basic structure:
+
+```typescript
+import { tool } from "@project-ajax/sdk";
+
+export const myTool = tool({
+  // Description of what this tool does - shown to the AI agent
+  description: "Search for items by keyword or ID",
+  // JSON Schema for the input the tool accepts
+  schema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        nullable: true,
+        description: "The search query"
+      },
+      limit: {
+        type: "number",
+        nullable: true,
+        description: "Maximum number of results"
+      },
+    },
+    required: [],
+    additionalProperties: false,
+  },
+  // Optional: JSON Schema for the output the tool returns
+  outputSchema: {
+    type: "object",
+    properties: {
+      results: {
+        type: "array",
+        items: { type: "string" },
+      },
+    },
+    required: ["results"],
+    additionalProperties: false,
+  },
+  // The function that executes when the tool is called
+  execute: async (input: { query?: string | null; limit?: number | null }) => {
+    // Destructure input with default values
+    const { query, limit = 10 } = input;
+    
+    // Perform your logic here
+    const results = await searchItems(query, limit);
+    
+    // Return data matching your outputSchema (if provided)
+    return { results };
+  },
+});
+```
+
+### 4. Deploy your function
+
+Deploy your functions to your Notion workspace with [**deploy**](#npx-workers-deploy):
+
+```bash
+npx workers deploy
+```
+
+This will build your worker bundle, upload it to Notion, and make your functions available in your workspace.
+
+### 5. Add secrets
+
+Your function might require sensitive values, like API tokens, to run. You can add [**secrets**](#npx-workers-secrets) to your function's run context. Secrets are exposed to your function as environment variables.
+
+Run the following to add secrets:
+
+```
+npx workers secrets set MY_SECRET_1=my-secret-value MY_SECRET_2=my-secret-value2
+```
+
+Then, you can reference these secret values in your function code using `process.env`, e.g. `process.env.MY_SECRET_1`.
+
+### 6. Run your function
+
+For slash commands, you can test your function in the Notion workspace you deployed to.
+
+For sync commands, your function is run automatically in the background. You can also run it via the CLI with [`exec`](#npx-workers-exec):
+
+```
+npx workers exec nameOfSyncCapability
+```
+
+When the command has finished executing, you should see a collection in your Notion sidebar that contains the synced data.
+
+You can also test slash commands using [`exec`](#npx-workers-exec). Specify which function inside the slash command you want to run (i.e. `executeSearch` or `executeSelect`). Pass in arguments using `arg=value` syntax:
+
+```
+npx workers exec mySlashCommand executeSearch query="myquery"
+```
+
+## Extensions reference
+
+### Slash commands
+
+You can write an extension that adds a new **slash command** to a Notion workspace. The slash command currently supported is a "search-then-execute" flow.
+
+For example, you can write a slash command to insert a Linear ticket:
+
+1. First, after selecting your slash command, the user enters a search query for a particular Linear ticket:
+
+<img src="./docs/select-ajax.png" style="width:400px" />
+
+2. After they select a ticket from the list, your extension will insert blocks into the page.
+
+The search query is powered by `executeSearch` and the select action triggers `executeSelect`.
+
+#### Properties
+
+- **`menuTitle`** (string, required): The title that appears in the slash command menu when users type `/`.
+- **`menuDescription`** (string, required): A description of what the slash command does, shown in the menu.
+- **`search`** (object, required): Configuration for the search interface.
+  - **`placeholder`** (string, required): Placeholder text shown in the search field.
+  - **`debounce`** (number, required): Milliseconds to wait before executing search after user stops typing.
+- **`executeSearch`** (function, required): Async function that handles search queries.
+  - **Parameters**: `query` (string) - The user's search input.
+  - **Returns**: Promise resolving to an object with `items` array, where each item has:
+    - `id` (string): Unique identifier for the item.
+    - `title` (string): Title displayed in search results.
+    - `description` (string, optional): Additional description text.
+- **`executeSelect`** (function, required): Async function that handles when a user selects an item.
+  - **Parameters**: `id` (string) - The id of the selected item.
+  - **Returns**: Promise resolving to an array of Notion blocks to insert into the page.
+
+### Sync
+
+The **sync** extension allows you to sync any data to a Notion collection. Every time a sync is run, data is upserted or deleted from the target Notion collection so that the collection matches the source.
+
+At the moment, syncs do not run automatically. Use **`exec`** to run a sync.
+
+#### Properties
+
+- **`primaryKeyProperty`** (string, required): The name of the property that serves as the unique identifier for each entry in the collection (e.g. `"id"`). This property must also be defined in the schema.
+- **`schema`** (object, required): Defines the structure of the Notion collection.
+  - **`dataSourceTitle`** (string, required): The name of the collection that will be created in Notion. Collections are instantiated in the user's sidebar.
+  - **`properties`** (object, required): An object mapping property names to their schema definitions. Use functions from `@project-ajax/sdk/schema` to define property types (e.g., `Schema.title()`, `Schema.richText()`).
+- **`execute`** (function, required): Async function that fetches and returns data to sync.
+  - **Parameters**: None (but can access `process.env` for secrets).
+  - **Returns**: Promise resolving to an array of entries, where each entry has:
+    - `key` (string): Unique identifier for the entry (maps to the `primaryKeyProperty`).
+    - `properties` (object): An object mapping property names to their values. Use functions from `@project-ajax/sdk/builder` to construct property values (e.g., `Builder.title()`, `Builder.richText()`).
+
+### Tools
+
+The **tool** extension allows custom agents in your Notion workspace to perform actions. When you connect a worker to a custom agent, the agent can invoke your tools based on their descriptions and schemas.
+
+Tools use JSON Schema to define their input and output structures, and the SDK validates data automatically.
+
+#### Properties
+
+- **`description`** (string, required): A clear description of what the tool does. This is shown to the AI agent to help it decide when to use the tool.
+- **`schema`** (JSONSchemaType, required): JSON Schema definition for the tool's input parameters. The input will be validated against this schema before execution.
+- **`outputSchema`** (JSONSchemaType, optional): JSON Schema definition for the tool's output. If provided, the output will be validated against this schema after execution.
+- **`execute`** (function, required): Async function that performs the tool's action.
+  - **Parameters**: `input` (typed according to your schema) - The validated input parameters.
+  - **Returns**: Promise resolving to output data (validated against `outputSchema` if provided).
+
+#### Error handling
+
+The tool system automatically handles three types of errors:
+
+- **`InvalidToolInputError`**: Thrown when input doesn't match the input schema.
+- **`InvalidToolOutputError`**: Thrown when output doesn't match the output schema (if provided).
+- **`ToolExecutionError`**: Thrown when the execute function throws an error.
+
+All errors are automatically caught and returned in a structured format, so you don't need to handle them in your `execute` function.
+
+#### JSON Schema types
+
+Your schemas should use standard JSON Schema format. Common patterns:
+
+**Object with required and optional properties:**
+```typescript
+{
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    age: { type: "number", nullable: true },
+    active: { type: "boolean", nullable: true },
+  },
+  // Only 'name' is required; age and active can be omitted
+  required: ["name"],
+  additionalProperties: false,
+}
+```
+
+**Arrays:**
+```typescript
+{
+  type: "array",
+  items: { type: "string" },
+}
+```
+
+**Enums:**
+```typescript
+{
+  type: "string",
+  enum: ["option1", "option2", "option3"],
+}
+```
+
+#### Testing tools
+
+You can test tools using [`exec`](#npx-workers-exec):
+
+```bash
+# Execute a tool without arguments
+npx workers exec myTool
+
+# Note: Currently, tools cannot accept arguments via CLI due to parser limitations.
+# To test tools with specific inputs, use them with a custom agent in Notion.
+```
+
+## CLI reference
+
+The `workers` CLI provides commands to authenticate, deploy, execute, and manage your Notion functions. All commands support global flags for configuration and debugging.
+
+### Global flags
+
+These flags are available on all commands:
+
+- **`--config <path>`**: Path to the config file to use (defaults to `workers.json`)
+- **`--debug`**: Enable debug logging
+
+### `npx workers auth`
+
+Commands for managing authentication with the Project Ajax platform.
+
+#### `npx workers auth login [token] [--env=<env>]`
+
+Login to the Project Ajax platform using a Workers API token.
+
+**Arguments:**
+
+- `token` (optional): A Workers API token. If not provided, opens a browser to create one.
+
+**Flags:**
+
+- `--env` (optional): The environment to use (`local`, `staging`, `dev`, or `prod`). Defaults to `prod`.
+
+**Examples:**
+
+```bash
+# Open browser to create a token
+npx workers auth login
+
+# Login with an existing token
+npx workers auth login v1.user.wAFygwEZ-...
+
+# Login to dev environment
+npx workers auth login --env=dev
+```
+
+#### `npx workers auth show`
+
+Display the currently configured authentication token.
+
+**Example:**
+
+```bash
+npx workers auth show
+```
+
+#### `npx workers auth logout`
+
+Remove the currently configured authentication token.
+
+**Example:**
+
+```bash
+npx workers auth logout
+```
+
+### `npx workers deploy`
+
+Deploy your worker to the Project Ajax platform. This command builds your worker bundle, uploads it to Notion, and saves the worker configuration.
+
+**Example:**
+
+```bash
+npx workers deploy
+```
+
+The deploy command will:
+
+1. Build your worker bundle from the current directory
+2. Upload the bundle to Notion
+3. Fetch and save worker capabilities
+4. Store the worker ID in your config file
+
+### `npx workers exec`
+
+Execute a worker capability with optional function and arguments.
+
+**Usage:**
+
+```bash
+npx workers exec <capabilityName> [functionName] [arg1=value1 arg2=value2...]
+```
+
+**Arguments:**
+
+- `capabilityName` (required): Name of the capability to execute
+- `functionName` (optional): For slash commands, specify which function to run (`executeSearch` or `executeSelect`)
+- `arguments` (optional): Key-value pairs as arguments. Supports both `key=value` and `key value` formats.
+
+**Flags:**
+
+- `--output <mode>`: Output mode for results. Options:
+  - `none`: No output
+  - `full`: Complete output
+  - `pager`: Paginate long output (default)
+
+**Examples:**
+
+```bash
+# Execute a sync capability
+npx workers exec tasksSync
+
+# Execute a slash command's search function
+npx workers exec taskSearch executeSearch query="ajax"
+
+# Execute with specific output mode
+npx workers exec taskSearch executeSearch query="test" --output=full
+```
+
+### `npx workers capabilities`
+
+Commands for managing worker capabilities.
+
+#### `npx workers capabilities list`
+
+List all capabilities for the deployed worker.
+
+**Example:**
+
+```bash
+npx workers capabilities list
+```
+
+This will display all capabilities with their names and types (e.g., `sync`, `slashCommand`).
+
+### `npx workers secrets`
+
+Commands for managing worker secrets. Secrets are exposed to your functions as environment variables via `process.env`.
+
+#### `npx workers secrets set <key> <value> [<key2> <value2>...]`
+
+Set one or more secrets for your worker. Supports multiple formats:
+
+**Formats:**
+
+- Space-separated: `key value`
+- Equals-separated: `key=value`
+- Colon-separated: `key:value`
+
+**Examples:**
+
+```bash
+# Set a single secret
+npx workers secrets set API_KEY my-secret-value
+
+# Set multiple secrets (space-separated)
+npx workers secrets set API_KEY my-key API_SECRET my-secret
+
+# Set multiple secrets (equals format)
+npx workers secrets set API_KEY=my-key API_SECRET=my-secret
+
+# Mix formats
+npx workers secrets set API_KEY=my-key DATABASE_URL my-db-url
+```
+
+#### `npx workers secrets list`
+
+List all secret keys for your worker. Note: Secret values are not displayed, only keys and creation timestamps.
+
+**Example:**
+
+```bash
+npx workers secrets list
+```
+
+#### `npx workers secrets rm <key>`
+
+Remove a secret from your worker.
+
+**Arguments:**
+
+- `key` (required): The secret key name to remove
+
+**Example:**
+
+```bash
+npx workers secrets rm API_KEY
+```
+
+### `npx workers connect`
+
+Commands for managing OAuth connections that store provider tokens as worker secrets. Connections appear in your runtime as environment variables (e.g., `process.env.NOTION_OAUTH_GOOGLE`).
+
+#### `npx workers connect providers`
+
+List the OAuth providers that are currently available for your workspace.
+
+```bash
+npx workers connect providers
+```
+
+#### `npx workers connect add <provider>`
+
+Start the OAuth flow in your browser for the specified provider. The command opens your default browser and also prints a fallback link.
+
+```bash
+npx workers connect add google
+```
+
+#### `npx workers connect list`
+
+Display all active OAuth connections for the deployed worker. The output includes the provider name, the environment variable exposed to your code, and when the connection was created.
+
+```bash
+npx workers connect list
+```
+
+#### `npx workers connect rm <provider>`
+
+Remove an OAuth connection (and the stored tokens) for the specified provider.
+
+```bash
+npx workers connect rm google
+```
+
+### Configuration file
+
+The CLI stores configuration in a `workers.json` file in your project directory. This file is automatically created and updated by the CLI commands. It contains:
+
+- **`environment`**: The current environment (`local`, `staging`, `dev`, or `prod`)
+- **`token`**: Your authentication token
+- **`workerId`**: The ID of your deployed worker
+
+You can specify a different config file using the `--config` flag on any command.

package/template/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@project-ajax/template",
+	"version": "0.0.0",
+	"main": "dist/index.js",
+	"private": true,
+	"scripts": {
+		"build": "tsc",
+		"check": "tsc --noEmit",
+		"dev": "tsx --watch src/index.ts",
+		"start": "node dist/index.js",
+		"bump-sdk": "npm install @project-ajax/sdk@latest"
+	},
+	"engines": {
+		"node": ">=22.0.0",
+		"npm": ">=10.9.4"
+	},
+	"devDependencies": {
+		"@types/node": "^22.9.0",
+		"tsx": "^4.20.6",
+		"typescript": "^5.8.0"
+	},
+	"dependencies": {
+		"@project-ajax/cli": ">=0.0.0",
+		"@project-ajax/sdk": ">=0.0.0"
+	}
+}

package/template/src/index.ts

@@ -0,0 +1,334 @@
+import { tool } from "@project-ajax/sdk";
+import type {
+	Block,
+	CalloutBlock,
+	ParagraphBlock,
+} from "@project-ajax/sdk/block";
+import * as Builder from "@project-ajax/sdk/builder";
+import * as Schema from "@project-ajax/sdk/schema";
+import { slashCommand } from "@project-ajax/sdk/slashCommand";
+import { sync } from "@project-ajax/sdk/sync";
+
+// Sample data for demonstration
+const sampleTasks = [
+	{
+		id: "task-1",
+		title: "Welcome to Project Ajax",
+		status: "Completed",
+		description: "This is a simple hello world example",
+	},
+	{
+		id: "task-2",
+		title: "Build your first worker",
+		status: "In Progress",
+		description: "Create a sync or slash command worker",
+	},
+	{
+		id: "task-3",
+		title: "Deploy to production",
+		status: "Todo",
+		description: "Share your worker with your team",
+	},
+];
+
+// Example sync worker that syncs sample tasks to a database
+export const tasksSync = sync({
+	primaryKeyProperty: "Task ID",
+
+	// Optional: Set to true to delete pages that are not returned from sync executions.
+	// By default (false), sync only creates and updates pages, never deletes them.
+	// deleteUnreturnedPages: true,
+
+	schema: {
+		dataSourceTitle: "Sample Tasks",
+		databaseIcon: Builder.notionIcon("checklist"),
+		properties: {
+			"Ticket Title": Schema.title(),
+			"Task ID": Schema.richText(),
+			Description: Schema.richText(),
+			Status: Schema.select([
+				{ name: "Completed", color: "green" },
+				{ name: "In Progress", color: "blue" },
+				{ name: "Todo", color: "default" },
+			]),
+		},
+	},
+
+	execute: async () => {
+		const emojiForStatus = (status: string) => {
+			switch (status) {
+				case "Completed":
+					return Builder.notionIcon("checkmark", "green");
+				case "In Progress":
+					return Builder.notionIcon("arrow-right", "blue");
+				case "Todo":
+					return Builder.notionIcon("clock", "lightgray");
+				default:
+					return Builder.notionIcon("question-mark", "lightgray");
+			}
+		};
+		// Return sample tasks as database entries
+		const objects = sampleTasks.map((task) => ({
+			key: task.id,
+			icon: emojiForStatus(task.status),
+			properties: {
+				"Ticket Title": Builder.title(task.title),
+				"Task ID": Builder.richText(task.id),
+				Description: Builder.richText(task.description),
+				Status: Builder.select(task.status),
+			},
+			pageContentMarkdown: `## ${task.title}\n\n${task.description}`,
+		}));
+
+		return {
+			objects,
+			done: true,
+		};
+	},
+});
+
+// Example slash command that searches and inserts sample tasks
+export const taskSearchSlashCommand = slashCommand({
+	menuTitle: "Insert Sample Task",
+	menuDescription: "Search for a sample task to insert",
+	search: {
+		placeholder: "Search for tasks...",
+		debounce: 300,
+	},
+	executeSearch: async (query: string) => {
+		// Filter tasks based on the search query
+		const filtered = sampleTasks.filter(
+			(task) =>
+				task.title.toLowerCase().includes(query.toLowerCase()) ||
+				task.description.toLowerCase().includes(query.toLowerCase()),
+		);
+
+		// Transform tasks into menu items
+		const items = filtered.map((task) => ({
+			id: task.id,
+			title: task.title,
+			description: `${task.status} • ${task.description}`,
+		}));
+
+		return { items };
+	},
+
+	executeSelect: async (taskId: string) => {
+		// Find the selected task
+		const task = sampleTasks.find((t) => t.id === taskId);
+
+		if (!task) {
+			return [];
+		}
+
+		// Create blocks to insert into the page
+		const calloutBlock: CalloutBlock = {
+			object: "block",
+			type: "callout",
+			callout: {
+				icon: {
+					type: "emoji",
+					emoji: "✨",
+				},
+				rich_text: [
+					{
+						type: "text",
+						text: {
+							content: `Task: ${task.id}`,
+							link: null,
+						},
+						plain_text: `Task: ${task.id}`,
+						href: null,
+						annotations: {
+							bold: true,
+							italic: false,
+							strikethrough: false,
+							underline: false,
+							code: false,
+							color: "default",
+						},
+					},
+				],
+				color: "blue_background",
+			},
+		};
+
+		const titleBlock: ParagraphBlock = {
+			object: "block",
+			type: "paragraph",
+			paragraph: {
+				rich_text: [
+					{
+						type: "text",
+						text: {
+							content: task.title,
+							link: null,
+						},
+						plain_text: task.title,
+						href: null,
+						annotations: {
+							bold: true,
+							italic: false,
+							strikethrough: false,
+							underline: false,
+							code: false,
+							color: "default",
+						},
+					},
+				],
+			},
+		};
+
+		const statusBlock: ParagraphBlock = {
+			object: "block",
+			type: "paragraph",
+			paragraph: {
+				rich_text: [
+					{
+						type: "text",
+						text: {
+							content: "Status: ",
+							link: null,
+						},
+						plain_text: "Status: ",
+						href: null,
+						annotations: {
+							bold: true,
+							italic: false,
+							strikethrough: false,
+							underline: false,
+							code: false,
+							color: "default",
+						},
+					},
+					{
+						type: "text",
+						text: {
+							content: task.status,
+							link: null,
+						},
+						plain_text: task.status,
+						href: null,
+						annotations: {
+							bold: false,
+							italic: false,
+							strikethrough: false,
+							underline: false,
+							code: false,
+							color:
+								task.status === "Completed"
+									? "green"
+									: task.status === "In Progress"
+										? "blue"
+										: "default",
+						},
+					},
+				],
+			},
+		};
+
+		const descriptionBlock: ParagraphBlock = {
+			object: "block",
+			type: "paragraph",
+			paragraph: {
+				rich_text: [
+					{
+						type: "text",
+						text: {
+							content: task.description,
+							link: null,
+						},
+						plain_text: task.description,
+						href: null,
+						annotations: {
+							bold: false,
+							italic: true,
+							strikethrough: false,
+							underline: false,
+							code: false,
+							color: "gray",
+						},
+					},
+				],
+			},
+		};
+
+		const blocks: Block[] = [
+			calloutBlock,
+			titleBlock,
+			statusBlock,
+			descriptionBlock,
+		];
+
+		return blocks;
+	},
+});
+
+// Example agent tool for retrieving task information
+export const taskSearchTool = tool({
+	title: "Task Search",
+	description:
+		"Look up sample tasks by ID or keyword. Helpful for demonstrating agent tool calls.",
+	schema: {
+		type: "object",
+		properties: {
+			taskId: {
+				type: "string",
+				nullable: true,
+				description: "Return a single task that matches the given task ID.",
+			},
+			query: {
+				type: "string",
+				nullable: true,
+				description:
+					"Match search terms against words in the task title or description.",
+			},
+		},
+		required: [],
+		additionalProperties: false,
+	},
+	execute: async (input: { taskId?: string | null; query?: string | null }) => {
+		const { taskId, query } = input;
+
+		let matchingTasks = sampleTasks;
+
+		if (taskId) {
+			matchingTasks = sampleTasks.filter((task) => task.id === taskId);
+		} else if (query) {
+			const normalizedQuery = query.trim().toLowerCase();
+
+			const terms = normalizedQuery.split(/\s+/).filter(Boolean);
+
+			if (terms.length > 0) {
+				const scoredTasks = sampleTasks
+					.map((task) => {
+						const title = task.title.toLowerCase();
+						const description = task.description.toLowerCase();
+						const matches = terms.reduce((count, term) => {
+							return title.includes(term) || description.includes(term)
+								? count + 1
+								: count;
+						}, 0);
+
+						return { task, matches };
+					})
+					.filter(({ matches }) => matches > 0)
+					.sort((a, b) => b.matches - a.matches);
+
+				matchingTasks = scoredTasks.map(({ task }) => task);
+			} else {
+				matchingTasks = [];
+			}
+		}
+
+		return {
+			count: matchingTasks.length,
+			tasks: matchingTasks.map((task) => ({
+				id: task.id,
+				title: task.title,
+				status: task.status,
+				description: task.description,
+			})),
+		};
+	},
+});

package/template/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "nodenext",
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"moduleResolution": "nodenext"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}