iterate 0.1.1 → 0.2.2

package/README.md

@@ -0,0 +1,134 @@
+# iterate
+
+⚠️⚠️⚠️ Coming soon! `npx iterate` is a work-in-progress CLI for managing [iterate.com](https://iterate.com) agents ⚠️⚠️⚠️
+
+CLI for Iterate.
+
+Runs as a thin bootstrapper that:
+
+1. Resolves an `iterate/iterate` checkout.
+2. Clones/install deps when needed.
+3. Loads `apps/os/backend/trpc/root.ts` from that checkout.
+4. Exposes commands like `iterate os ...` and `iterate whoami`.
+
+## Requirements
+
+- Node `>=22`
+- `git`
+- `pnpm` or `corepack`
+
+## Quick start
+
+Run without installing globally:
+
+```bash
+npx iterate --help
+```
+
+Initial setup (writes auth + launcher config):
+
+```bash
+npx iterate setup \
+  --base-url https://dev-yourname-os.dev.iterate.com \
+  --admin-password-env-var-name SERVICE_AUTH_TOKEN \
+  --user-email dev-yourname@iterate.com \
+  --repo-path managed \
+  --auto-install true \
+  --scope global
+```
+
+Then run commands:
+
+```bash
+npx iterate whoami
+npx iterate os project list
+```
+
+## Commands
+
+- `iterate setup` - configure auth + launcher defaults
+- `iterate doctor` - print resolved config/runtime info
+- `iterate install` - force clone/install for resolved checkout
+- `iterate whoami`
+- `iterate os ...`
+
+## Config file
+
+Config path:
+
+`${XDG_CONFIG_HOME:-~/.config}/iterate/config.json`
+
+Config shape:
+
+```json
+{
+  "global": {
+    "repoPath": "~/.local/share/iterate/repo",
+    "repoRef": "main",
+    "repoUrl": "https://github.com/iterate/iterate.git",
+    "autoInstall": true
+  },
+  "workspaces": {
+    "/absolute/workspace/path": {
+      "baseUrl": "https://dev-yourname-os.dev.iterate.com",
+      "adminPasswordEnvVarName": "SERVICE_AUTH_TOKEN",
+      "userEmail": "dev-yourname@iterate.com",
+      "repoPath": "/absolute/path/to/iterate",
+      "autoInstall": false
+    }
+  }
+}
+```
+
+Merge precedence is shallow:
+
+`global` -> `workspaces[process.cwd()]`
+
+## Repo checkout resolution
+
+`repoPath` resolution order:
+
+1. `ITERATE_REPO_DIR`
+2. `workspaces[process.cwd()].repoPath`
+3. `global.repoPath`
+4. nearest parent directory containing `.git`, `pnpm-workspace.yaml`, and `apps/os/backend/trpc/root.ts`
+5. default managed checkout path `${XDG_DATA_HOME:-~/.local/share}/iterate/repo`
+
+`repoPath` shortcuts in `setup`:
+
+- `local` - nearest local iterate checkout
+- `managed` - default managed checkout path
+
+Environment overrides:
+
+- `ITERATE_REPO_DIR`
+- `ITERATE_REPO_REF`
+- `ITERATE_REPO_URL`
+- `ITERATE_AUTO_INSTALL` (`1/true` or `0/false`)
+
+## Local iterate dev
+
+If you run inside an `iterate/iterate` clone, the CLI auto-detects it. In that mode, default `autoInstall` is `false`.
+
+You can pin explicitly:
+
+```bash
+npx iterate setup \
+  --base-url https://dev-yourname-os.dev.iterate.com \
+  --admin-password-env-var-name SERVICE_AUTH_TOKEN \
+  --user-email dev-yourname@iterate.com \
+  --repo-path local \
+  --auto-install false \
+  --scope workspace
+```
+
+## Publishing (maintainers)
+
+From repo root:
+
+```bash
+pnpm --filter ./packages/iterate typecheck
+pnpm eslint packages/iterate/bin/iterate.js
+pnpm prettier --check packages/iterate
+pnpm --filter ./packages/iterate publish --access public
+```

package/bin/iterate.js

@@ -0,0 +1,744 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import * as prompts from "@clack/prompts";
+import { createTRPCClient, httpLink } from "@trpc/client";
+import { initTRPC } from "@trpc/server";
+import { createAuthClient } from "better-auth/client";
+import { adminClient } from "better-auth/client/plugins";
+import superjson from "superjson";
+import { createCli } from "trpc-cli";
+import { proxify } from "trpc-cli/dist/proxify.js";
+import { z } from "zod/v4";
+
+const DEFAULT_REPO_URL = "https://github.com/iterate/iterate.git";
+const XDG_CONFIG_PATH = join(
+  process.env.XDG_CONFIG_HOME ? process.env.XDG_CONFIG_HOME : join(homedir(), ".config"),
+  "iterate",
+  "config.json",
+);
+const XDG_REPO_DIR = join(
+  process.env.XDG_DATA_HOME ? process.env.XDG_DATA_HOME : join(homedir(), ".local", "share"),
+  "iterate",
+  "repo",
+);
+const DEFAULT_REPO_DIR = XDG_REPO_DIR;
+const CONFIG_PATH = XDG_CONFIG_PATH;
+const APP_ROUTER_PATH = join("apps", "os", "backend", "trpc", "root.ts");
+
+/**
+ * @typedef {{
+ *   repoPath?: string;
+ *   repoRef?: string;
+ *   repoUrl?: string;
+ *   autoInstall?: boolean;
+ * }} LauncherConfig
+ */
+
+/**
+ * @typedef {{
+ *   global?: Record<string, unknown>;
+ *   workspaces?: Record<string, Record<string, unknown>>;
+ * } & Record<string, unknown>} ConfigFile
+ */
+
+/** @typedef {"env" | "config" | "cwd" | "default"} RepoDirSource */
+
+/**
+ * @typedef {{
+ *   repoDir: string;
+ *   repoDirSource: RepoDirSource;
+ *   repoRef?: string;
+ *   repoUrl: string;
+ *   autoInstall: boolean;
+ *   cwdRepoDir?: string;
+ *   launcherConfig: LauncherConfig;
+ * }} RuntimeOptions
+ */
+
+/**
+ * @typedef {{
+ *   command: string;
+ *   args: string[];
+ *   cwd?: string;
+ *   env?: Record<string, string | undefined>;
+ * }} SpawnOptions
+ */
+
+/**
+ * @typedef {{
+ *   repoDir: string;
+ *   repoRef?: string;
+ *   repoUrl: string;
+ * }} CheckoutOptions
+ */
+
+const isAgent =
+  process.env.AGENT === "1" ||
+  process.env.OPENCODE === "1" ||
+  Boolean(process.env.OPENCODE_SESSION) ||
+  Boolean(process.env.CLAUDE_CODE);
+
+const t = initTRPC.meta().create();
+
+const SetupInput = z.object({
+  baseUrl: z
+    .string()
+    .describe(`Base URL for os API (for example https://dev-yourname-os.dev.iterate.com)`),
+  adminPasswordEnvVarName: z.string().describe("Env var name containing admin password"),
+  userEmail: z.string().describe("User email to impersonate for os calls"),
+  repoPath: z.string().describe("Path to iterate checkout (or 'local' / 'managed' shortcuts)"),
+  autoInstall: z.boolean().describe("Auto install dependencies when missing"),
+  scope: z.enum(["workspace", "global"]).describe("Where to store launcher config"),
+});
+
+const AuthConfig = z.object({
+  baseUrl: z.string(),
+  adminPasswordEnvVarName: z.string(),
+  userEmail: z.string(),
+});
+
+/** @param {string} message */
+const log = (message) => {
+  process.stderr.write(`[iterate] ${message}\n`);
+};
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+const isObject = (value) => {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+};
+
+/** @param {unknown} value */
+const nonEmptyString = (value) => {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+/** @param {string} input */
+const normalizePath = (input) => {
+  if (input === "~") {
+    return homedir();
+  }
+  if (input.startsWith("~/")) {
+    return join(homedir(), input.slice(2));
+  }
+  if (isAbsolute(input)) {
+    return input;
+  }
+  return resolve(input);
+};
+
+/** @param {unknown} value */
+const parseBoolean = (value) => {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const normalized = value.toLowerCase();
+  if (normalized === "1" || normalized === "true") {
+    return true;
+  }
+  if (normalized === "0" || normalized === "false") {
+    return false;
+  }
+  return undefined;
+};
+
+/** @returns {ConfigFile} */
+const readConfigFile = () => {
+  if (!existsSync(CONFIG_PATH)) {
+    return {};
+  }
+  const rawText = readFileSync(CONFIG_PATH, "utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid JSON in ${CONFIG_PATH}: ${detail}`);
+  }
+
+  if (!isObject(parsed)) {
+    throw new Error(`${CONFIG_PATH} must contain a JSON object.`);
+  }
+  return parsed;
+};
+
+/** @param {unknown} launcher */
+const sanitizeLauncherConfig = (launcher) => {
+  if (!isObject(launcher)) {
+    return {};
+  }
+  return {
+    repoPath: nonEmptyString(launcher.repoPath),
+    repoRef: nonEmptyString(launcher.repoRef),
+    repoUrl: nonEmptyString(launcher.repoUrl),
+    autoInstall: typeof launcher.autoInstall === "boolean" ? launcher.autoInstall : undefined,
+  };
+};
+
+/** @param {ConfigFile} configFile */
+const getGlobalConfig = (configFile) => {
+  return isObject(configFile.global) ? configFile.global : {};
+};
+
+/**
+ * @param {ConfigFile} configFile
+ * @param {string} workspacePath
+ */
+const getWorkspaceConfig = (configFile, workspacePath) => {
+  const workspaces = isObject(configFile.workspaces) ? configFile.workspaces : {};
+  const rawWorkspaceConfig = workspaces[workspacePath];
+  return isObject(rawWorkspaceConfig) ? rawWorkspaceConfig : {};
+};
+
+/**
+ * @param {ConfigFile} configFile
+ * @param {string} workspacePath
+ */
+const getMergedWorkspaceConfig = (configFile, workspacePath) => {
+  return {
+    ...getGlobalConfig(configFile),
+    ...getWorkspaceConfig(configFile, workspacePath),
+  };
+};
+
+/** @param {string} workspacePath */
+const readLauncherConfig = (workspacePath) => {
+  const configFile = readConfigFile();
+  return sanitizeLauncherConfig(getMergedWorkspaceConfig(configFile, workspacePath));
+};
+
+/**
+ * @param {{
+ *   launcherPatch: Partial<LauncherConfig>;
+ *   workspacePatch?: Record<string, unknown>;
+ *   scope: "workspace" | "global";
+ *   workspacePath: string;
+ * }} options
+ */
+const writeLauncherConfig = ({ launcherPatch, workspacePatch, scope, workspacePath }) => {
+  const configFile = readConfigFile();
+  const existingGlobal = getGlobalConfig(configFile);
+  const existingWorkspaces = isObject(configFile.workspaces) ? configFile.workspaces : {};
+
+  const nextGlobal = scope === "global" ? { ...existingGlobal, ...launcherPatch } : existingGlobal;
+  const nextWorkspaces =
+    scope === "workspace" || workspacePatch
+      ? {
+          ...existingWorkspaces,
+          [workspacePath]: {
+            ...getWorkspaceConfig(configFile, workspacePath),
+            ...(scope === "workspace" ? launcherPatch : {}),
+            ...(workspacePatch ?? {}),
+          },
+        }
+      : existingWorkspaces;
+
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  const { launcher: _unusedLauncher, ...rest } = configFile;
+  const next = {
+    ...rest,
+    global: nextGlobal,
+    workspaces: nextWorkspaces,
+  };
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+};
+
+/** @param {string} dir */
+const isIterateRepo = (dir) => {
+  return (
+    existsSync(join(dir, ".git")) &&
+    existsSync(join(dir, "pnpm-workspace.yaml")) &&
+    existsSync(join(dir, APP_ROUTER_PATH))
+  );
+};
+
+/** @param {string} startDir */
+const findNearestIterateRepo = (startDir) => {
+  let current = resolve(startDir);
+  for (;;) {
+    if (isIterateRepo(current)) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+};
+
+/** @returns {RuntimeOptions} */
+const resolveRuntimeOptions = () => {
+  const launcherConfig = readLauncherConfig(process.cwd());
+  const cwdRepoDir = findNearestIterateRepo(process.cwd());
+  const envRepoDir = nonEmptyString(process.env.ITERATE_REPO_DIR);
+
+  let repoDir;
+  /** @type {RepoDirSource} */
+  let repoDirSource;
+
+  if (envRepoDir) {
+    repoDir = normalizePath(envRepoDir);
+    repoDirSource = "env";
+  } else if (launcherConfig.repoPath) {
+    repoDir = normalizePath(launcherConfig.repoPath);
+    repoDirSource = "config";
+  } else if (cwdRepoDir) {
+    repoDir = cwdRepoDir;
+    repoDirSource = "cwd";
+  } else {
+    repoDir = DEFAULT_REPO_DIR;
+    repoDirSource = "default";
+  }
+
+  const repoRef = nonEmptyString(process.env.ITERATE_REPO_REF) ?? launcherConfig.repoRef;
+  const repoUrl =
+    nonEmptyString(process.env.ITERATE_REPO_URL) ?? launcherConfig.repoUrl ?? DEFAULT_REPO_URL;
+  const autoInstall =
+    parseBoolean(process.env.ITERATE_AUTO_INSTALL) ??
+    launcherConfig.autoInstall ??
+    (repoDirSource === "cwd" ? false : true);
+
+  return {
+    repoDir,
+    repoDirSource,
+    repoRef,
+    repoUrl,
+    autoInstall,
+    cwdRepoDir,
+    launcherConfig,
+  };
+};
+
+/** @param {string} workspacePath */
+const readAuthConfig = (workspacePath) => {
+  const configFile = readConfigFile();
+  const mergedConfig = getMergedWorkspaceConfig(configFile, workspacePath);
+  const parsed = AuthConfig.safeParse(mergedConfig);
+  if (!parsed.success) {
+    throw new Error(
+      `Config file ${CONFIG_PATH} is missing auth config for ${workspacePath}. Have you run \`iterate setup\`?\n${z.prettifyError(parsed.error)}`,
+    );
+  }
+  return parsed.data;
+};
+
+/** @param {string[] | undefined} setCookies */
+const setCookiesToCookieHeader = (setCookies) => {
+  const byName = new Map();
+  for (const c of setCookies ?? []) {
+    const pair = c.split(";")[0]?.trim();
+    if (!pair) continue;
+    const eq = pair.indexOf("=");
+    if (eq === -1) continue;
+    byName.set(pair.slice(0, eq), pair.slice(eq + 1));
+  }
+  return [...byName.entries()].map(([k, v]) => `${k}=${v}`).join("; ");
+};
+
+const impersonationUserIdCache = new Map();
+
+/**
+ * @param {{
+ *   superadminAuthClient: any;
+ *   userEmail: string;
+ *   baseUrl: string;
+ * }} options
+ */
+const resolveImpersonationUserId = async ({ superadminAuthClient, userEmail, baseUrl }) => {
+  const normalizedEmail = userEmail.trim().toLowerCase();
+  const cacheKey = `${baseUrl}::${normalizedEmail}`;
+  const cachedUserId = impersonationUserIdCache.get(cacheKey);
+  if (cachedUserId) {
+    return cachedUserId;
+  }
+
+  /** @type {any[]} */
+  let users = [];
+
+  try {
+    const result = await superadminAuthClient.admin.listUsers({
+      query: {
+        filterField: "email",
+        filterOperator: "eq",
+        filterValue: normalizedEmail,
+        limit: 10,
+      },
+      fetchOptions: {
+        throw: true,
+      },
+    });
+    users = Array.isArray(result?.users) ? result.users : [];
+  } catch {
+    const result = await superadminAuthClient.admin.listUsers({
+      query: {
+        searchField: "email",
+        searchOperator: "contains",
+        searchValue: normalizedEmail,
+        limit: 100,
+      },
+      fetchOptions: {
+        throw: true,
+      },
+    });
+    users = Array.isArray(result?.users) ? result.users : [];
+  }
+
+  const exactMatches = users.filter(
+    (user) =>
+      user &&
+      typeof user === "object" &&
+      "email" in user &&
+      typeof user.email === "string" &&
+      user.email.toLowerCase() === normalizedEmail &&
+      "id" in user &&
+      typeof user.id === "string",
+  );
+
+  if (exactMatches.length === 0) {
+    throw new Error(`No user found with email ${userEmail}`);
+  }
+  if (exactMatches.length > 1) {
+    throw new Error(`Multiple users found with email ${userEmail}`);
+  }
+
+  const resolvedUserId = exactMatches[0].id;
+  impersonationUserIdCache.set(cacheKey, resolvedUserId);
+  return resolvedUserId;
+};
+
+/** @param {z.infer<typeof AuthConfig>} authConfig */
+const authDance = async (authConfig) => {
+  let superadminSetCookie;
+  const authClient = createAuthClient({
+    baseURL: authConfig.baseUrl,
+    fetchOptions: {
+      throw: true,
+    },
+  });
+  const password = process.env[authConfig.adminPasswordEnvVarName];
+  if (!password) {
+    throw new Error(`Password not found in env var ${authConfig.adminPasswordEnvVarName}`);
+  }
+
+  await authClient.signIn.email({
+    email: "superadmin@nustom.com",
+    password,
+    fetchOptions: {
+      throw: true,
+      onResponse: (ctx) => {
+        superadminSetCookie = ctx.response.headers.getSetCookie();
+      },
+    },
+  });
+
+  const superadminAuthClient = createAuthClient({
+    baseURL: authConfig.baseUrl,
+    fetchOptions: {
+      throw: true,
+      onRequest: (ctx) => {
+        ctx.headers.set("origin", authConfig.baseUrl);
+        ctx.headers.set("cookie", setCookiesToCookieHeader(superadminSetCookie));
+      },
+    },
+    plugins: [adminClient()],
+  });
+
+  const userId = await resolveImpersonationUserId({
+    superadminAuthClient,
+    userEmail: authConfig.userEmail,
+    baseUrl: authConfig.baseUrl,
+  });
+
+  let impersonateSetCookie;
+  await superadminAuthClient.admin.impersonateUser({
+    userId,
+    fetchOptions: {
+      throw: true,
+      onResponse: (ctx) => {
+        impersonateSetCookie = ctx.response.headers.getSetCookie();
+      },
+    },
+  });
+
+  const userCookies = setCookiesToCookieHeader(impersonateSetCookie);
+
+  const userClient = createAuthClient({
+    baseURL: authConfig.baseUrl,
+    fetchOptions: {
+      throw: true,
+      onRequest: (ctx) => {
+        ctx.headers.set("origin", authConfig.baseUrl);
+        ctx.headers.set("cookie", userCookies);
+      },
+    },
+  });
+
+  return { userCookies, userClient };
+};
+
+/** @param {string} repoDir */
+const loadAppRouter = async (repoDir) => {
+  const appRouterPath = join(repoDir, APP_ROUTER_PATH);
+  if (!existsSync(appRouterPath)) {
+    throw new Error(`Could not find ${APP_ROUTER_PATH} under ${repoDir}.`);
+  }
+  const rootModule = await import(pathToFileURL(appRouterPath).href);
+  if (!rootModule || typeof rootModule !== "object" || !("appRouter" in rootModule)) {
+    throw new Error(`Failed to load appRouter from ${appRouterPath}`);
+  }
+  return rootModule.appRouter;
+};
+
+/** @param {unknown} error */
+const commandMissing = (error) => {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+};
+
+/** @param {SpawnOptions} options */
+const run = ({ command, args, cwd, env }) => {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      stdio: "inherit",
+    });
+
+    child.on("error", (error) => {
+      rejectPromise(error);
+    });
+
+    child.on("close", (code, signal) => {
+      if (signal) {
+        rejectPromise(new Error(`${command} exited with signal ${signal}`));
+        return;
+      }
+      resolvePromise(code ?? 0);
+    });
+  });
+};
+
+/** @param {SpawnOptions} options */
+const runChecked = async ({ command, args, cwd, env }) => {
+  const code = await run({ command, args, cwd, env });
+  if (code !== 0) {
+    throw new Error(`Command failed (${code}): ${command} ${args.join(" ")}`);
+  }
+};
+
+/** @param {CheckoutOptions} options */
+const ensureRepoCheckout = async ({ repoDir, repoRef, repoUrl }) => {
+  if (existsSync(repoDir)) {
+    if (!existsSync(join(repoDir, APP_ROUTER_PATH))) {
+      throw new Error(`Expected ${APP_ROUTER_PATH} in ${repoDir}.`);
+    }
+    if (!existsSync(join(repoDir, ".git"))) {
+      throw new Error(`Expected git checkout at ${repoDir}, but .git is missing.`);
+    }
+    return;
+  }
+
+  mkdirSync(dirname(repoDir), { recursive: true });
+  const cloneArgs = ["clone", "--depth", "1"];
+  if (repoRef) {
+    cloneArgs.push("--branch", repoRef, "--single-branch");
+  }
+  cloneArgs.push(repoUrl, repoDir);
+
+  log(`cloning iterate repo into ${repoDir}`);
+  try {
+    await runChecked({ command: "git", args: cloneArgs });
+    const envClientPath = join(repoDir, "apps/os/env-client.ts");
+    // todo: remove this as soon as this branch is merged into main
+    writeFileSync(
+      envClientPath,
+      readFileSync(envClientPath, "utf8").replace("import.meta.env.", "import.meta.env?."),
+    );
+  } catch (error) {
+    if (commandMissing(error)) {
+      throw new Error("git is required but was not found on PATH.");
+    }
+    throw error;
+  }
+};
+
+/** @param {string} repoDir */
+const hasInstalledDependencies = (repoDir) => {
+  return existsSync(join(repoDir, "node_modules", ".modules.yaml"));
+};
+
+/** @param {{ repoDir: string }} options */
+const installDependencies = async ({ repoDir }) => {
+  log("installing dependencies with pnpm");
+  const installArgs = ["install", "--frozen-lockfile"];
+  try {
+    await runChecked({
+      command: "corepack",
+      args: ["pnpm", ...installArgs],
+      cwd: repoDir,
+    });
+    return;
+  } catch (error) {
+    if (!commandMissing(error)) {
+      throw error;
+    }
+  }
+
+  try {
+    await runChecked({
+      command: "pnpm",
+      args: installArgs,
+      cwd: repoDir,
+    });
+  } catch (error) {
+    if (commandMissing(error)) {
+      throw new Error("pnpm/corepack is required but was not found on PATH.");
+    }
+    throw error;
+  }
+};
+
+/** @param {string} repoDir */
+const getRuntimeProcedures = async (repoDir) => {
+  const appRouter = await loadAppRouter(repoDir);
+  const proxiedRouter = proxify(appRouter, async () => {
+    return createTRPCClient({
+      links: [
+        httpLink({
+          url: `${readAuthConfig(process.cwd()).baseUrl}/api/trpc/`,
+          transformer: superjson,
+          fetch: async (request, init) => {
+            const authConfig = readAuthConfig(process.cwd());
+            const { userCookies } = await authDance(authConfig);
+            const headers = new Headers(init?.headers);
+            headers.set("cookie", userCookies);
+            return fetch(request, { ...init, headers });
+          },
+        }),
+      ],
+    });
+  });
+
+  return {
+    whoami: t.procedure.mutation(async () => {
+      const authConfig = readAuthConfig(process.cwd());
+      const { userClient } = await authDance(authConfig);
+      return await userClient.getSession();
+    }),
+    os: proxiedRouter,
+  };
+};
+
+const launcherProcedures = {
+  doctor: t.procedure
+    .meta({ description: "Show launcher config and resolved runtime options" })
+    .mutation(async () => {
+      const runtime = resolveRuntimeOptions();
+      return {
+        configPath: CONFIG_PATH,
+        repoDir: runtime.repoDir,
+        repoDirSource: runtime.repoDirSource,
+        autoInstall: runtime.autoInstall,
+        repoRef: runtime.repoRef ?? null,
+        repoUrl: runtime.repoUrl,
+        cwdRepoDir: runtime.cwdRepoDir ?? null,
+        repoExists: existsSync(runtime.repoDir),
+        dependenciesInstalled: hasInstalledDependencies(runtime.repoDir),
+      };
+    }),
+  setup: t.procedure
+    .input(SetupInput)
+    .meta({ description: "Configure auth + launcher defaults for current workspace" })
+    .mutation(async ({ input }) => {
+      const runtime = resolveRuntimeOptions();
+
+      const rawRepoPath = input.repoPath.trim().toLowerCase();
+      let repoPath = normalizePath(input.repoPath);
+      if (rawRepoPath === "managed") {
+        repoPath = DEFAULT_REPO_DIR;
+      } else if (rawRepoPath === "local") {
+        if (!runtime.cwdRepoDir) {
+          throw new Error(
+            "'local' repoPath was selected but current directory is not inside an iterate repo",
+          );
+        }
+        repoPath = runtime.cwdRepoDir;
+      }
+
+      const next = writeLauncherConfig({
+        launcherPatch: { repoPath, autoInstall: input.autoInstall },
+        workspacePatch: {
+          baseUrl: input.baseUrl,
+          adminPasswordEnvVarName: input.adminPasswordEnvVarName,
+          userEmail: input.userEmail,
+        },
+        scope: input.scope,
+        workspacePath: process.cwd(),
+      });
+      return {
+        configPath: CONFIG_PATH,
+        launcher: sanitizeLauncherConfig(getMergedWorkspaceConfig(next, process.cwd())),
+        scope: input.scope,
+      };
+    }),
+  install: t.procedure
+    .meta({ description: "Clone repo if needed, then run pnpm install" })
+    .mutation(async () => {
+      const runtime = resolveRuntimeOptions();
+      await ensureRepoCheckout(runtime);
+      await installDependencies({ repoDir: runtime.repoDir });
+      return { repoDir: runtime.repoDir };
+    }),
+};
+
+/** @param {string[]} args */
+const runCli = async (args) => {
+  const runtime = resolveRuntimeOptions();
+  await ensureRepoCheckout(runtime);
+
+  if (runtime.autoInstall && !hasInstalledDependencies(runtime.repoDir)) {
+    await installDependencies({ repoDir: runtime.repoDir });
+  }
+
+  const runtimeProcedures = await getRuntimeProcedures(runtime.repoDir);
+  const router = t.router({
+    ...launcherProcedures,
+    ...runtimeProcedures,
+  });
+
+  const cli = createCli({
+    router,
+    name: "iterate",
+    version: "0.0.1",
+    description: "Iterate CLI",
+  });
+
+  process.argv = [process.argv[0], process.argv[1], ...args];
+  await cli.run({
+    prompts: isAgent ? undefined : prompts,
+  });
+};
+
+const main = async () => {
+  const args = process.argv.slice(2);
+  await runCli(args);
+};
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -1,28 +1,46 @@
 {
   "name": "iterate",
-  "version": "0.1.1",
-  "description": "some iterator functions",
-  "main": "index.js",
-  "directories": {
-    "test": "test"
-  },
-  "devDependencies": {
-    "it-is": "~1.0.2"
-  },
-  "scripts": {
-    "test": "synct test/*.js"
-  },
+  "version": "0.2.2",
+  "description": "CLI for iterate",
+  "license": "Apache-2.0",
+  "type": "module",
   "repository": {
     "type": "git",
-    "url": "git://github.com/dominictarr/iterate.git"
+    "url": "git+https://github.com/iterate/iterate.git",
+    "directory": "packages/iterate"
+  },
+  "homepage": "https://github.com/iterate/iterate#readme",
+  "bugs": {
+    "url": "https://github.com/iterate/iterate/issues"
   },
   "keywords": [
-    "iterator",
-    "each",
-    "sync",
-    "map",
-    "filter"
+    "iterate",
+    "cli",
+    "trpc"
   ],
-  "author": "Dominic Tarr <dominic.tarr@gmail.com> (dominictarr.com)",
-  "license": "MIT"
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "iterate": "./bin/iterate.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "node --check ./bin/iterate.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "@trpc/client": "^11.7.2",
+    "@trpc/server": "^11.7.2",
+    "better-auth": "1.4.3",
+    "superjson": "^2.2.2",
+    "trpc-cli": "^0.12.2",
+    "zod": "4.1.12"
+  }
 }

package/LICENSE

@@ -1,24 +0,0 @@
-The MIT License
-
-Copyright (c) 2013 Dominic Tarr
-
-Permission is hereby granted, free of charge, 
-to any person obtaining a copy of this software and 
-associated documentation files (the "Software"), to 
-deal in the Software without restriction, including 
-without limitation the rights to use, copy, modify, 
-merge, publish, distribute, sublicense, and/or sell 
-copies of the Software, and to permit persons to whom 
-the Software is furnished to do so, 
-subject to the following conditions:
-
-The above copyright notice and this permission notice 
-shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR 
-ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.markdown

@@ -1,14 +0,0 @@
-# iterator
-
-some iterator functions, 
-  * each
-  * map
-  * filter
-  * times
-  * map
-  * find
-  * mapKeys
-  * mapToArray
-
-all work objects and on arrays
-

package/index.js

@@ -1,152 +0,0 @@
-
-//
-// adds all the fields from obj2 onto obj1
-//
-
-var each = exports.each = function (obj,iterator){
- var keys = Object.keys(obj)
- keys.forEach(function (key){
-  iterator(obj[key],key,obj) 
- })
-}
-
-var RX = /sadf/.constructor
-function rx (iterator ){
-  return iterator instanceof RX ? function (str) { 
-      var m = iterator.exec(str)
-      return m && (m[1] ? m[1] : m[0]) 
-    } : iterator
-}
-
-var times = exports.times = function () {
-  var args = [].slice.call(arguments)
-    , iterator = rx(args.pop())
-    , m = args.pop()
-    , i = args.shift()
-    , j = args.shift()
-    , diff, dir
-    , a = []
-    
-    i = 'number' === typeof i ? i : 1
-    diff = j ? j - i : 1
-    dir = i < m
-    if(m == i)
-      throw new Error('steps cannot be the same: '+m+', '+i)
-  for (; dir ? i <= m : m <= i; i += diff)
-    a.push(iterator(i))
-  return a
-}
-
-var map = exports.map = function (obj, iterator){
-  iterator = rx(iterator)
-  if(Array.isArray(obj))
-    return obj.map(iterator)
-  if('number' === typeof obj)
-    return times.apply(null, [].slice.call(arguments))  
-  //return if null ?  
-  var keys = Object.keys(obj)
-    , r = {}
-  keys.forEach(function (key){
-    r[key] = iterator(obj[key],key,obj) 
-  })
-  return r
-}
-
-var findReturn = exports.findReturn = function (obj, iterator) {
-  iterator = rx(iterator)
-  if(obj == null)
-    return
-  var keys = Object.keys(obj)
-    , l = keys.length
-  for (var i = 0; i < l; i ++) {
-    var key = keys[i]
-      , value = obj[key]
-    var r = iterator(value, key)
-    if(r) return r
-  }
-}
-
-var find = exports.find = function (obj, iterator) { 
-  iterator = rx(iterator)
-  return findReturn (obj, function (v, k) {
-    var r = iterator(v, k)
-    if(r) return v
-  })
-}
-
-var findKey = exports.findKey = function (obj, iterator) { 
-  iterator = rx(iterator)
-  return findReturn (obj, function (v, k) {
-    var r = iterator(v, k)
-    if(r) return k
-  })
-}
-
-var filter = exports.filter = function (obj, iterator){
-  iterator = rx (iterator)
-
-  if(Array.isArray(obj))
-    return obj.filter(iterator)
-  
-  var keys = Object.keys(obj)
-    , r = {}
-  keys.forEach(function (key){
-    var v
-    if(iterator(v = obj[key],key,obj))
-      r[key] = v
-  })
-  return r 
-}
-
-var mapKeys = exports.mapKeys = function (ary, iterator){
-  var r = {}
-  iterator = rx(iterator)
-  each(ary, function (v,k){
-    r[v] = iterator(v,k)
-  })
-  return r
-}
-
-
-var mapToArray = exports.mapToArray = function (ary, iterator){
-  var r = []
-  iterator = rx(iterator)
-  each(ary, function (v,k){
-    r.push(iterator(v,k))
-  })
-  return r
-}
-
-var path = exports.path = function (object, path) {
-
-  for (var i in path) {
-    if(object == null) return undefined
-    var key = path[i]
-    object = object[key]
-  }
-  return object
-}
-
-/*
-NOTE: naive implementation. 
-`match` must not contain circular references.
-*/
-
-var setPath = exports.setPath = function (object, path, value) {
-
-  for (var i in path) {
-    var key = path[i]
-    if(object[key] == null) object[key] = ( 
-      i + 1 == path.length ? value : {}
-    )
-    object = object[key]
-  }
-}
-
-var join = exports.join = function (A, B, it) {
-  each(A, function (a, ak) {
-    each(B, function (b, bk) {
-      it(a, b, ak, bk)
-    })
-  })
-}

package/test/objects.synct.js

@@ -1,188 +0,0 @@
-var objects = require('..')
-  , it = require('it-is')
-
-exports ['each'] = function (){
-  var on = {a: 1,b: 2, c: 3}, count = 0
-  objects.each(on, function(v,k){
-    it(v).equal(on[k])
-    count ++
-  })
-  it(count).equal(3)
-}
-exports ['map'] = function (){
-
-  var on = {a: 1,b: 2, c: 3}, count = 0
-  var off = 
-    objects.map(on, function(v,k){
-      it(v).equal(on[k])
-      count ++
-      return v * 2
-    })
-  it(count).equal(3)
-  it(off).deepEqual({
-    a: 2, b: 4,c: 6
-  })
-}
-
-exports ['map -- {}'] = function (){
-
-  var on = {}, count = 0
-  var off = 
-    objects.map(on, function(v,k){
-      count ++
-    })
-  it(count).equal(0)
-  it(off).deepEqual({})
-}
-
-exports ['map -- {}'] = function (){
-
-  var on = {}, count = 0
-  var off = 
-    objects.map(on, function(v,k){
-      count ++
-    })
-  it(count).equal(0)
-  it(off).deepEqual({})
-}
-
-exports ['map on numbers -- start at 1'] = function () {
-  
-  var seven = objects.map(7, function (n) {
-      return n
-  })
-
-  it(seven).deepEqual([1,2,3,4,5,6,7])
-  
-}
-
-exports ['map on numbers: 0 - 8'] = function () {
-  
-  var seven = objects.map(0, 8, function (n) {
-      return n
-  })
-
-  it(seven).deepEqual([0,1,2,3,4,5,6,7,8])
-
-}
-
-exports ['map even numbers: 2,4...12'] = function () {
-  
-  var seven = objects.map(2, 4, 12, function (n) {
-      return n
-  })
-
-  it(seven).deepEqual([2,4,6,8,10,12])
-}
-
-exports ['map even numbers: 12, 10...2 in reverse'] = function () {
-  
-  var seven = objects.map(12, 10, 2, function (n) {
-      return n
-  })
-
-  it(seven).deepEqual([2,4,6,8,10,12].reverse())
-
-}
-
-
-exports ['filter'] = function (){
-  
-  var on = {a: 1,b: 2, c: 3, d:4, e:5, f:6, g:7}, count = 0
- 
-  it(objects.filter(on, function (x){
-    return !(x % 2)
-  })).deepEqual({b: 2, d:4, f:6})
-}
-
-exports ['filter with regexp'] = function (){
-  
-  var on = [ '.git',
-    'test',
-    'objects.js',
-    'index.js',
-    'package.json',
-    'types.js',
-    'readme.markdown',
-    '.gitignore',
-    'arrays.js' ], count = 0
- 
-  it(objects.filter(on, /^.*\.js$/))
-  .deepEqual([ 
-    'objects.js',
-    'index.js',
-    'types.js',
-    'arrays.js' ])
-}
-
-exports ['mapKeys -- create a object from a list of keys and a function'] = function (){
-
-  var keys = ['foo','bar','xux']
-  
-  it(objects.mapKeys(keys, function (k){
-      return k.toUpperCase()
-  })).deepEqual({foo: 'FOO', bar: 'BAR', xux: 'XUX'})
-
-}
-
-exports ['mapToArray'] = function (){
-
-  var on = {a: 1,b: 2, c: 3, d:4, e:5, f:6, g:7}, count = 0
-
-  it(objects.mapToArray(on,function (v){
-    return v
-  })).deepEqual([1,2,3,4,5,6,7])
-  
-}
-
-exports ['find'] = function () {
-
-  //
-  // sometime need to stop before the end, find is like that 
-  //
-
-  var numbers = [3, 5, 3, 7, 77, 21, 4]
-
-  it(objects.find(numbers, function (e) { return !(e % 2)})).equal(4)
-  it(objects.findKey(numbers, function (e) { return !(e % 2)})).equal(6)
-  it(objects.findReturn(numbers, function (e) { return !(e % 2)})).equal(true)
-
-  it(objects.find([], function () {})).equal(null)
-  it(objects.find(null, function () {})).equal(null)
-
-}
-
-exports ['path'] = function () {
-
-  var a1 = {A: 1}
-  
-  it(objects.path(a1, ['A'])).equal(1)
-  it(objects.path({A: {B: 4}}, ['A', 'B'])).equal(4)
-  it(objects.path({A: {B: 4}}, ['A', 'C'])).strictEqual(undefined)
-  it(objects.path(null, ['A', 'C'])).strictEqual(undefined) 
-  it(objects.path({Z: [0, 1, 2]}, ['Z', 2])).strictEqual(2) 
-  it(objects.path({Z: [0, 1, 2]}, ['Z', 0])).strictEqual(0) 
-  it(objects.path({Z: [0, 1, 2]}, ['Z', 0, 'T'])).strictEqual(undefined) 
-  it(objects.path({Z: null}, ['Z', 0, 'T'])).strictEqual(undefined) 
-  it(objects.path({Z: null}, ['Z'])).strictEqual(null) 
-
-}
-
-exports ['setPath'] = function () {
-
-  var x = {}
-    , c = Math.random()
-    , z = Math.random()
-  objects.setPath(x, ['a','b','c'], c)
-  it.equal(x.a.b.c, c)
-  objects.setPath(x, ['z'], z)
-  it.equal(x.z, z)
-}
-
-exports['join'] = function () {
-  var ary = []
-  objects.join('abc'.split(''), 'ijk'.split(''), function (a, i) {
-    ary.push([a, i])
-  })
-  it.equal(ary.length, 9)
-}