feat: Array to Twig migration part 1 (#534)

IMPORTANT: This is part 1 of a 2 part change. After this is merged, we rename the repo and env variables then merge part 2

### TL;DR

Renamed the product from "Array" to "Twig" across the codebase, including configuration files, protocol handlers, and user-facing text.

### What changed?

- Renamed all user-facing instances of "Array" to "Twig" in the UI, window titles, and documentation
- Updated configuration file paths from `.array/` to `.twig/` and `array.json` to `twig.json`
- Added support for both `twig://` and legacy `array://` protocol handlers for deep linking
- Implemented migration logic to automatically move existing `.array` directories to `.twig`
- Maintained backward compatibility with legacy paths and configuration files
- Updated environment variables (keeping `ARRAY_` prefix for now with a note about future migration to `TWIG_`)
- Preserved app data paths for compatibility with existing installations

### How to test?

1. Verify the app name appears as "Twig" in window titles and UI elements
2. Confirm both `twig://` and `array://` deep links work correctly
3. Test that existing workspaces in `.array` are properly migrated to `.twig`
4. Verify that both `twig.json` and legacy `array.json` configuration files are recognized
5. Check that environment variables are correctly set in workspace terminals

### Why make this change?

This rename from "Array" to "Twig" represents a product rebranding decision. The implementation maintains backward compatibility with existing installations while establishing the new brand identity across the codebase. The migration logic ensures a smooth transition for existing users by automatically moving directories and supporting legacy configuration paths.

Author: k11kirky

CLAUDE.md

@@ -1,27 +1,27 @@
-# Array Development Guide
+# Twig Development Guide
 
 ## Project Structure
 
 - Monorepo with pnpm workspaces and turbo
-- `apps/array` - Electron desktop app (React + Vite)
+- `apps/array` - Twig Electron desktop app (React + Vite)
 - `packages/agent` - TypeScript agent framework wrapping Claude Agent SDK
 
 ## Commands
 
 - `pnpm install` - Install all dependencies
-- `pnpm dev` - Run both agent (watch) and array app via mprocs
+- `pnpm dev` - Run both agent (watch) and twig app via mprocs
 - `pnpm dev:agent` - Run agent package in watch mode only
-- `pnpm dev:array` - Run array desktop app only
+- `pnpm dev:array` - Run twig desktop app only
 - `pnpm build` - Build all packages (turbo)
 - `pnpm typecheck` - Type check all packages
 - `pnpm lint` - Lint and auto-fix with biome
 - `pnpm format` - Format with biome
 - `pnpm test` - Run tests across all packages
 
-### Array App Specific
+### Twig App Specific
 
 - `pnpm --filter array test` - Run vitest tests
-- `pnpm --filter array typecheck` - Type check array app
+- `pnpm --filter array typecheck` - Type check twig app
 - `pnpm --filter array package` - Package electron app
 - `pnpm --filter array make` - Make distributable
 

README.md

@@ -1,14 +1,14 @@
 > [!IMPORTANT]
-> Array is pre-alpha and not production-ready. Interested? Email jonathan@posthog.com
+> Twig is pre-alpha and not production-ready. Interested? Email jonathan@posthog.com
 
 
-# PostHog Array Monorepo
+# PostHog Twig Monorepo
 
-This is the monorepo for PostHog's Array apps and the agent framework that powers them.
+This is the monorepo for PostHog's Twig apps and the agent framework that powers them.
 
 ## Projects
 
-- **[apps/array](./apps/array)** - Array desktop application (Electron)
+- **[apps/array](./apps/array)** - Twig desktop application (Electron)
 - **[apps/mobile](./apps/mobile)** - PostHog mobile app (React Native / Expo)
 - **[packages/agent](./packages/agent)** - The TypeScript agent framework
 
@@ -90,16 +90,19 @@ array-monorepo/
 └── package.json        # Root package.json
 ```
 
-## Workspace Configuration (array.json)
+## Workspace Configuration (twig.json)
 
-Array supports per-repository configuration through an `array.json` file. This lets you define scripts that run automatically when workspaces are created or destroyed.
+Twig supports per-repository configuration through a `twig.json` file (or legacy `array.json`). This lets you define scripts that run automatically when workspaces are created or destroyed.
 
 ### File Locations
 
-Array searches for configuration in this order:
+Twig searches for configuration in this order (first match wins):
 
-1. `.array/{workspace-name}/array.json` - Workspace-specific config
-2. `array.json` - Repository root config
+1. `.twig/{workspace-name}/twig.json` - Workspace-specific config (new)
+2. `.twig/{workspace-name}/array.json` - Workspace-specific config (legacy)
+3. `.array/{workspace-name}/array.json` - Workspace-specific config (legacy location)
+4. `twig.json` - Repository root config (new)
+5. `array.json` - Repository root config (legacy)
 
 ### Schema
 
@@ -153,7 +156,7 @@ Clean up Docker containers:
 
 ## Workspace Environment Variables
 
-Array automatically sets environment variables in all workspace terminals and scripts. These are available in `init`, `start`, and `destroy` scripts, as well as any terminal sessions opened within a workspace.
+Twig automatically sets environment variables in all workspace terminals and scripts. These are available in `init`, `start`, and `destroy` scripts, as well as any terminal sessions opened within a workspace.
 
 | Variable | Description | Example |
 |----------|-------------|---------|

apps/array/forge.config.ts

@@ -131,8 +131,8 @@ const config: ForgeConfig = {
         "{**/*.node,**/spawn-helper,**/.vite/build/claude-cli/**,**/node_modules/node-pty/**,**/node_modules/@parcel/**,**/node_modules/file-icon/**}",
     },
     prune: false,
-    name: "Array",
-    executableName: "Array",
+    name: "Twig",
+    executableName: "Twig",
     icon: "./build/app-icon", // Forge adds .icns/.ico/.png based on platform
     appBundleId: "com.posthog.array",
     appCategoryType: "public.app-category.productivity",

apps/array/src/main/bootstrap.ts

@@ -13,7 +13,7 @@ const isDev = !app.isPackaged;
 
 // Set different app names for separate single-instance locks
 const appName = isDev ? "array-dev" : "Array";
-app.setName(isDev ? "Array (Development)" : "Array");
+app.setName(isDev ? "Twig (Development)" : "Twig");
 
 const userDataPath = path.join(app.getPath("appData"), "@posthog", appName);
 app.setPath("userData", userDataPath);

apps/array/src/main/index.ts

@@ -95,7 +95,9 @@ app.on("open-url", (event, url) => {
 
 // Handle deep link URLs on Windows/Linux (second instance sends URL via command line)
 app.on("second-instance", (_event, commandLine) => {
-  const url = commandLine.find((arg) => arg.startsWith("array://"));
+  const url = commandLine.find(
+    (arg) => arg.startsWith("twig://") || arg.startsWith("array://"),
+  );
   if (url) {
     const deepLinkService = container.get<DeepLinkService>(
       MAIN_TOKENS.DeepLinkService,
@@ -166,10 +168,10 @@ function createWindow(): void {
   // Set up menu for keyboard shortcuts
   const template: MenuItemConstructorOptions[] = [
     {
-      label: "Array",
+      label: "Twig",
       submenu: [
         {
-          label: "About Array",
+          label: "About Twig",
           click: () => {
             const commit = __BUILD_COMMIT__ ?? "dev";
             const buildDate = __BUILD_DATE__ ?? "dev";
@@ -187,8 +189,8 @@ function createWindow(): void {
             dialog
               .showMessageBox({
                 type: "info",
-                title: "About Array",
-                message: "Array",
+                title: "About Twig",
+                message: "Twig",
                 detail: info,
                 buttons: ["Copy", "OK"],
                 defaultId: 1,
@@ -348,7 +350,9 @@ app.whenReady().then(() => {
     }
   } else {
     // On Windows/Linux, the URL comes via command line arguments
-    const deepLinkUrl = process.argv.find((arg) => arg.startsWith("array://"));
+    const deepLinkUrl = process.argv.find(
+      (arg) => arg.startsWith("twig://") || arg.startsWith("array://"),
+    );
     if (deepLinkUrl) {
       deepLinkService.handleUrl(deepLinkUrl);
     }

apps/array/src/main/lib/shellManager.ts

@@ -36,7 +36,7 @@ function buildShellEnv(
     env.LC_MONETARY = locale;
   }
 
-  env.TERM_PROGRAM = "Array";
+  env.TERM_PROGRAM = "Twig";
   env.COLORTERM = "truecolor";
   env.FORCE_COLOR = "3";
 

apps/array/src/main/services/deep-link/service.ts

@@ -4,7 +4,8 @@ import { logger } from "../../lib/logger.js";
 
 const log = logger.scope("deep-link-service");
 
-const PROTOCOL = "array";
+const PROTOCOL = "twig";
+const LEGACY_PROTOCOL = "array";
 
 export type DeepLinkHandler = (
   path: string,
@@ -30,11 +31,14 @@ export class DeepLinkService {
       return;
     }
 
-    // Production: register the protocol
+    // Production: register both new and legacy protocols
     app.setAsDefaultProtocolClient(PROTOCOL);
+    app.setAsDefaultProtocolClient(LEGACY_PROTOCOL);
 
     this.protocolRegistered = true;
-    log.info(`Registered '${PROTOCOL}' protocol handler`);
+    log.info(
+      `Registered '${PROTOCOL}' and '${LEGACY_PROTOCOL}' protocol handlers`,
+    );
   }
 
   public registerHandler(key: string, handler: DeepLinkHandler): void {
@@ -53,11 +57,15 @@ export class DeepLinkService {
    * Handle an incoming deep link URL
    *
    * NOTE: Strips the protocol and main key, passing only dynamic segments to handlers.
+   * Supports both twig:// and legacy array:// protocols.
    */
   public handleUrl(url: string): boolean {
     log.info("Received deep link:", url);
 
-    if (!url.startsWith(`${PROTOCOL}://`)) {
+    const isTwigProtocol = url.startsWith(`${PROTOCOL}://`);
+    const isLegacyProtocol = url.startsWith(`${LEGACY_PROTOCOL}://`);
+
+    if (!isTwigProtocol && !isLegacyProtocol) {
       log.warn("URL does not match protocol:", url);
       return false;
     }

apps/array/src/main/services/settingsStore.ts

@@ -1,3 +1,4 @@
+import { existsSync, renameSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { app } from "electron";
@@ -7,10 +8,38 @@ interface SettingsSchema {
   worktreeLocation: string;
 }
 
+const LEGACY_DIR_NAME = ".array";
+const CURRENT_DIR_NAME = ".twig";
+
 function getDefaultWorktreeLocation(): string {
-  return path.join(os.homedir(), ".array");
+  return path.join(os.homedir(), CURRENT_DIR_NAME);
+}
+
+function getLegacyWorktreeLocation(): string {
+  return path.join(os.homedir(), LEGACY_DIR_NAME);
+}
+
+/**
+ * Migrate ~/.array to ~/.twig if needed (one-time migration)
+ */
+function migrateWorktreeDirectory(): void {
+  const legacyPath = getLegacyWorktreeLocation();
+  const newPath = getDefaultWorktreeLocation();
+
+  // Only migrate if legacy exists and new doesn't
+  if (existsSync(legacyPath) && !existsSync(newPath)) {
+    try {
+      renameSync(legacyPath, newPath);
+    } catch {
+      // If rename fails (e.g., cross-device), leave as-is
+      // User can manually migrate or continue using legacy location
+    }
+  }
 }
 
+// Run migration before store initialization
+migrateWorktreeDirectory();
+
 const schema = {
   worktreeLocation: {
     type: "string" as const,
@@ -27,6 +56,23 @@ export const settingsStore = new Store<SettingsSchema>({
   },
 });
 
+/**
+ * Migrate stored worktree setting from ~/.array to ~/.twig if it was the default
+ */
+function migrateWorktreeSetting(): void {
+  const stored = settingsStore.get("worktreeLocation");
+  const legacyDefault = getLegacyWorktreeLocation();
+  const newDefault = getDefaultWorktreeLocation();
+
+  // If user had the legacy default, update to new default
+  if (stored === legacyDefault && existsSync(newDefault)) {
+    settingsStore.set("worktreeLocation", newDefault);
+  }
+}
+
+// Run setting migration after store initialization
+migrateWorktreeSetting();
+
 export function getWorktreeLocation(): string {
   return settingsStore.get("worktreeLocation", getDefaultWorktreeLocation());
 }

apps/array/src/main/services/shell/service.ts

@@ -40,7 +40,7 @@ function buildShellEnv(
   }
 
   Object.assign(env, {
-    TERM_PROGRAM: "Array",
+    TERM_PROGRAM: "Twig",
     COLORTERM: "truecolor",
     FORCE_COLOR: "3",
     ...additionalEnv,

apps/array/src/main/services/workspace/configLoader.ts

@@ -20,43 +20,48 @@ export async function loadConfig(
   worktreePath: string,
   worktreeName: string,
 ): Promise<LoadConfigResult> {
-  // Search order:
-  // 1. .array/{WORKSPACE_NAME}/array.json (workspace-specific)
-  // 2. {repo-root}/array.json (repository root)
+  // Search order (twig.json takes precedence over legacy array.json):
+  // 1. .twig/{WORKSPACE_NAME}/twig.json (workspace-specific, new)
+  // 2. .twig/{WORKSPACE_NAME}/array.json (workspace-specific, legacy)
+  // 3. .array/{WORKSPACE_NAME}/array.json (workspace-specific, legacy location)
+  // 4. {repo-root}/twig.json (repository root, new)
+  // 5. {repo-root}/array.json (repository root, legacy)
 
-  const workspaceConfigPath = path.join(
-    worktreePath,
-    ".array",
-    worktreeName,
-    "array.json",
-  );
+  const workspaceConfigPaths = [
+    path.join(worktreePath, ".twig", worktreeName, "twig.json"),
+    path.join(worktreePath, ".twig", worktreeName, "array.json"),
+    path.join(worktreePath, ".array", worktreeName, "array.json"),
+  ];
 
-  const repoConfigPath = path.join(worktreePath, "array.json");
+  const repoConfigPaths = [
+    path.join(worktreePath, "twig.json"),
+    path.join(worktreePath, "array.json"),
+  ];
 
-  // Try workspace-specific config first
-  const workspaceResult = await tryLoadConfig(workspaceConfigPath);
-  if (workspaceResult.config) {
-    log.info(`Loaded config from workspace: ${workspaceConfigPath}`);
-    return { config: workspaceResult.config, source: "workspace" };
-  }
-  if (workspaceResult.errors) {
-    log.warn(
-      `Invalid config at ${workspaceConfigPath}: ${workspaceResult.errors.join(", ")}`,
-    );
-    return { config: null, source: null };
+  // Try workspace-specific configs first
+  for (const configPath of workspaceConfigPaths) {
+    const result = await tryLoadConfig(configPath);
+    if (result.config) {
+      log.info(`Loaded config from workspace: ${configPath}`);
+      return { config: result.config, source: "workspace" };
+    }
+    if (result.errors) {
+      log.warn(`Invalid config at ${configPath}: ${result.errors.join(", ")}`);
+      return { config: null, source: null };
+    }
   }
 
-  // Try repo root config
-  const repoResult = await tryLoadConfig(repoConfigPath);
-  if (repoResult.config) {
-    log.info(`Loaded config from repo root: ${repoConfigPath}`);
-    return { config: repoResult.config, source: "repo" };
-  }
-  if (repoResult.errors) {
-    log.warn(
-      `Invalid config at ${repoConfigPath}: ${repoResult.errors.join(", ")}`,
-    );
-    return { config: null, source: null };
+  // Try repo root configs
+  for (const configPath of repoConfigPaths) {
+    const result = await tryLoadConfig(configPath);
+    if (result.config) {
+      log.info(`Loaded config from repo root: ${configPath}`);
+      return { config: result.config, source: "repo" };
+    }
+    if (result.errors) {
+      log.warn(`Invalid config at ${configPath}: ${result.errors.join(", ")}`);
+      return { config: null, source: null };
+    }
   }
 
   return { config: null, source: null };