@zodiaceco/create 0.0.0-stage → 2.7.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @zodiaceco/create
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Starts a [Zodiac](https://zodiac.eco) constellation project: your organisation's onchain accounts, roles, and permissions as code.
+
+```bash
+npm create @zodiaceco@latest my-org
+```
+
+`pnpm dlx @zodiaceco/create` and `bunx @zodiaceco/create` work the same, installing with pnpm or Bun, as does `zodiac create` from [`@zodiaceco/sdk`](https://www.npmjs.com/package/@zodiaceco/sdk).
+
+It copies the constellation template into `my-org`, installs its dependencies with the package manager you ran it with, and offers to connect the project to Zodiac: that opens your browser to sign in, mints an API key for the project and pulls your org's accounts. Last, it commits the project to a new git repository.
+
+| Option         | What it does                                                     |
+| -------------- | ---------------------------------------------------------------- |
+| `--pm <name>`  | install with `npm`, `pnpm`, `yarn` or `bun` instead              |
+| `--no-install` | don't install dependencies                                       |
+| `--no-git`     | don't initialize a git repository                                |
+| `--no-auth`    | don't connect the project to Zodiac                              |
+| `--overwrite`  | empty a directory that isn't empty (keeping its `.git`)          |
+| `-y, --yes`    | don't ask, take the defaults (as without a terminal, e.g. in CI) |
+
+Without a terminal, or with `--yes`, it never connects to Zodiac, since that needs a browser. Run `npm run pull` in the project to do it later.
+
+The template lives in [`templates/constellation`](./templates/constellation).

package/dist/index.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import * as prompts from "@clack/prompts";
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+//#region src/packageManager.ts
+const PACKAGE_MANAGERS = [
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun"
+];
+const isPackageManager = (name) => PACKAGE_MANAGERS.includes(name);
+/**
+* The package manager this runs under: `npm create`, `pnpm create`,
+* `yarn create` and `bun create` each say so in `npm_config_user_agent`.
+*/
+const detectPackageManager = (userAgent = process.env.npm_config_user_agent) => {
+	const name = userAgent?.split("/")[0];
+	return isPackageManager(name) ? name : "npm";
+};
+/** The command that runs a `package.json` script with `packageManager`. */
+const runScript = (packageManager, script) => {
+	switch (packageManager) {
+		case "npm":
+		case "bun": return [
+			packageManager,
+			"run",
+			script
+		];
+		default: return [packageManager, script];
+	}
+};
+//#endregion
+//#region src/scaffold.ts
+/** Copies the template into `targetDir` and makes it the project `name`. */
+const scaffold = ({ templateDir, targetDir, name, sdkVersion }) => {
+	mkdirSync(targetDir, { recursive: true });
+	cpSync(templateDir, targetDir, { recursive: true });
+	renameSync(join(targetDir, "_gitignore"), join(targetDir, ".gitignore"));
+	const packageJsonPath = join(targetDir, "package.json");
+	const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	packageJson.name = name;
+	packageJson.dependencies["@zodiaceco/sdk"] = `^${sdkVersion}`;
+	writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+};
+/** Whether `dir` is missing or holds nothing but a git repository. */
+const isEmptyDir = (dir) => !existsSync(dir) || readdirSync(dir).every((entry) => entry === ".git");
+/** Removes everything in `dir` but its git repository. */
+const emptyDir = (dir) => {
+	for (const entry of readdirSync(dir)) if (entry !== ".git") rmSync(join(dir, entry), {
+		recursive: true,
+		force: true
+	});
+};
+/** A valid package name after the directory the project goes in. */
+const toPackageName = (targetDir) => basename(resolve(targetDir)).toLowerCase().replace(/[^a-z0-9._~-]+/g, "-").replace(/^[._-]+|-+$/g, "") || "zodiac-constellation";
+//#endregion
+//#region src/workspace.ts
+/** The workspace every org starts with, and the one the template names. */
+const DEFAULT_WORKSPACE = "Default workspace";
+const ENTRYPOINT = join("constellation", "index.ts");
+/**
+* The workspaces of the org the project is authorized for, after `zodiac
+* pull` wrote their accounts to `.zodiac/`. None before.
+*/
+const readWorkspaces = (projectDir) => {
+	try {
+		const codegen = createRequire(import.meta.url)(join(projectDir, ".zodiac"));
+		return Object.keys(codegen.accounts ?? {});
+	} catch {
+		return [];
+	}
+};
+/** Points the template's constellation at `workspace`. */
+const setWorkspace = (projectDir, workspace) => {
+	const path = join(projectDir, ENTRYPOINT);
+	writeFileSync(path, readFileSync(path, "utf8").replace(`workspace: ${JSON.stringify(DEFAULT_WORKSPACE)}`, () => `workspace: ${JSON.stringify(workspace)}`));
+};
+//#endregion
+//#region src/index.ts
+const HELP = `Usage: npm create @zodiaceco [directory] [options]
+
+Starts a Zodiac constellation project in [directory].
+
+Options:
+  --pm <name>      package manager to install with: ${PACKAGE_MANAGERS.join(", ")} (default: the one running this)
+  --no-install     don't install dependencies
+  --no-git         don't initialize a git repository
+  --no-auth        don't connect the project to Zodiac
+  --overwrite      empty a directory that isn't empty
+  -y, --yes        don't ask, take the defaults
+  -h, --help       print this help
+  -v, --version    print the version
+`;
+const DEFAULT_DIRECTORY = "zodiac-constellation";
+const ownVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const templateDir = fileURLToPath(new URL("../templates/constellation", import.meta.url));
+const main = async () => {
+	const { values, positionals } = parseArgs({
+		allowPositionals: true,
+		options: {
+			pm: { type: "string" },
+			"no-install": { type: "boolean" },
+			"no-git": { type: "boolean" },
+			"no-auth": { type: "boolean" },
+			overwrite: { type: "boolean" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			},
+			help: {
+				type: "boolean",
+				short: "h"
+			},
+			version: {
+				type: "boolean",
+				short: "v"
+			}
+		}
+	});
+	if (values.help) return console.log(HELP);
+	if (values.version) return console.log(ownVersion);
+	if (values.pm != null && !isPackageManager(values.pm)) throw new UsageError(`--pm must be one of ${PACKAGE_MANAGERS.join(", ")}, not "${values.pm}".`);
+	const interactive = process.stdin.isTTY === true && !values.yes;
+	const packageManager = values.pm ?? detectPackageManager();
+	prompts.intro("Zodiac constellation");
+	const directory = positionals[0] ?? (interactive ? orCancel(await prompts.text({
+		message: "Where should the project go?",
+		placeholder: DEFAULT_DIRECTORY,
+		defaultValue: DEFAULT_DIRECTORY
+	})) : DEFAULT_DIRECTORY);
+	const targetDir = resolve(directory);
+	if (!isEmptyDir(targetDir)) {
+		if (!(values.overwrite || interactive && orCancel(await prompts.confirm({
+			message: `${directory} isn't empty. Remove what's in it?`,
+			initialValue: false
+		})))) throw new UsageError(`${directory} isn't empty. Pick another directory, or pass --overwrite.`);
+		emptyDir(targetDir);
+	}
+	scaffold({
+		templateDir,
+		targetDir,
+		name: toPackageName(targetDir),
+		sdkVersion: ownVersion
+	});
+	prompts.log.success(`Created the project in ${directory}`);
+	const install = !values["no-install"] && (!interactive || orCancel(await prompts.confirm({ message: `Install dependencies with ${packageManager}?` })));
+	const installed = install && run([packageManager, "install"], targetDir);
+	if (install && !installed) prompts.log.warn(`Installing with ${packageManager} failed.`);
+	const connect = installed && interactive && !values["no-auth"] && orCancel(await prompts.confirm({ message: "Connect the project to Zodiac now? This opens your browser to sign in." }));
+	const connected = connect && run(runScript(packageManager, "pull"), targetDir);
+	if (connect && !connected) prompts.log.warn("Connecting to Zodiac failed.");
+	if (connected) await pickWorkspace(targetDir);
+	if (!values["no-git"]) initGit(targetDir);
+	const next = [
+		`cd ${shellQuote(relative(process.cwd(), targetDir) || ".")}`,
+		!installed && `${packageManager} install`,
+		!connected && runScript(packageManager, "pull").join(" "),
+		"edit constellation/index.ts and constellation/roles/",
+		runScript(packageManager, "push").join(" ")
+	].filter(Boolean);
+	prompts.note(next.join("\n"), "Next steps");
+	prompts.outro("README.md explains the rest.");
+};
+/** Points the constellation at the org's workspace, asking if it has several. */
+const pickWorkspace = async (targetDir) => {
+	const workspaces = readWorkspaces(targetDir);
+	if (workspaces.length === 0) return;
+	const workspace = workspaces.length === 1 ? workspaces[0] : orCancel(await prompts.select({
+		message: "Which workspace is the constellation for?",
+		options: workspaces.map((value) => ({
+			value,
+			label: value
+		})),
+		initialValue: workspaces.includes("Default workspace") ? DEFAULT_WORKSPACE : workspaces[0]
+	}));
+	if (workspace !== "Default workspace") {
+		setWorkspace(targetDir, workspace);
+		prompts.log.success(`The constellation is for the workspace "${workspace}".`);
+	}
+};
+/** Commits the new project to a repository of its own, if git is there. */
+const initGit = (targetDir) => {
+	const git = (...args) => spawnSync("git", args, {
+		cwd: targetDir,
+		stdio: "ignore"
+	}).status === 0;
+	if (!git("--version")) return;
+	if (git("rev-parse", "--is-inside-work-tree")) return;
+	if (!git("init", "--quiet")) return;
+	if (git("add", "--all") && git("commit", "--quiet", "-m", "Initial commit from @zodiaceco/create")) prompts.log.success("Initialized a git repository");
+	else prompts.log.info("Initialized a git repository, without committing to it.");
+};
+/** Runs a command in `cwd` with its output shown. True if it succeeded. */
+const run = ([command, ...args], cwd) => spawnSync(command, args, {
+	cwd,
+	stdio: "inherit",
+	shell: process.platform === "win32"
+}).status === 0;
+const shellQuote = (path) => /^[\w./~-]+$/.test(path) ? path : `"${path.replace(/(["\\$`])/g, "\\$1")}"`;
+var UsageError = class extends Error {};
+/** An answer, or the end of the run when it was cancelled with Ctrl-C. */
+const orCancel = (value) => {
+	if (prompts.isCancel(value)) {
+		prompts.cancel("Cancelled.");
+		process.exit(1);
+	}
+	return value;
+};
+main().catch((error) => {
+	if (error instanceof UsageError) prompts.cancel(error.message);
+	else console.error(error);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@zodiaceco/create",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.7.0",
+  "description": "Start a Zodiac constellation project: npm create @zodiaceco",
+  "author": "Zodiac Labs GmbH",
+  "license": "LGPL-3.0-only",
+  "homepage": "https://github.com/zodiaceco/zodiac-sdk/tree/main/create",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zodiaceco/zodiac-sdk.git",
+    "directory": "create"
+  },
+  "type": "module",
+  "bin": {
+    "create": "dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check:types": "tsc -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.21",
+    "tsdown": "~0.21.9",
+    "typescript": "^5.9.2"
+  }
+}

package/templates/constellation/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{ts,json}]
+charset = utf-8
+indent_style = space
+indent_size = 2

package/templates/constellation/.prettierignore

@@ -0,0 +1,2 @@
+node_modules
+package.json

package/templates/constellation/.prettierrc

@@ -0,0 +1 @@
+{}

package/templates/constellation/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["esbenp.prettier-vscode"]
+}

package/templates/constellation/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "editor.formatOnSave": true,
+  "editor.tabSize": 2
+}

package/templates/constellation/CLAUDE.md

@@ -0,0 +1,28 @@
+# Zodiac Constellation — agent notes
+
+This repo is a **Zodiac constellation**: a TypeScript description of an org's smart-account graph (Safes, mods, users, permissions). `npm run push` sends the spec to Zodiac, which diffs it against onchain state and gives a UI to review + sign the transactions.
+
+User-facing docs are in `README.md` — read it before suggesting edits to `constellation/`.
+
+## Project map
+
+- `constellation/index.ts` — entrypoint. **Only exported values get pushed.**
+- `constellation/roles/<role>/` — `members.ts` (addresses) + `permissions.ts`
+  (a list of entries: `custom`, `defikit`, `swap`, `transfer` from
+  `@zodiaceco/sdk/actions`, or a bare `allow` kit permission).
+- `constellation/allowances/` — reusable Roles allowance objects (key, refill, period, ...).
+  A permission draws on one by naming its key: `c.withinAllowance("usdc_payouts")`.
+- `zodiac.config.ts` — contracts the `allow` kit should know about.
+- `.zodiac/` — generated codegen; **never edit by hand**. Re-run `npm run pull` (or `pull-org` / `pull-contracts`) to refresh.
+
+## Conventions
+
+- Entries **describe, they never compile**. `defikit` stores a protocol, verb
+  and parameters; `swap` stores its token lists. The permissions are built when
+  the constellation is deployed, so a stored revision never carries a copy of
+  what a preset meant on the day it was written.
+
+- Import `constellation`, `allow`, `c` and the `Members` / `Permissions` types from `@zodiaceco/sdk`, the entries from `@zodiaceco/sdk/actions`.
+- After editing `zodiac.config.ts` (contracts) or anything that changes referenced accounts/users, run `npm run pull` so the generated types match.
+- Any package manager works: run the scripts with `npm run`, `pnpm`, `yarn` or `bun run`. The `zodiac` CLI loads `.env` itself.
+- `npx zodiac push --dry-run` prints what would be pushed, without pulling or an API key: use it to check an edit.

package/templates/constellation/README.md

@@ -0,0 +1,262 @@
+# Zodiac constellation
+
+Your organisation's onchain accounts, roles, and permissions as code.
+
+## What's a Zodiac constellation?
+
+A **constellation** is a declarative description of an organisation's smart account graph: which Safes you operate, what roles each one delegates, who's allowed to do what, and how the pieces are wired together.
+
+You write the desired state in TypeScript. Zodiac figures out the diff against what's currently onchain, plans the most efficient set of transactions, and gives you a UI to review and sign them. Anyone with access to the workspace sees the same plan and the same audit trail.
+
+## Why manage your accounts as code?
+
+Treat your smart account graph the way you treat infrastructure: declare it as code, version it in git, ship it like software. AI-assisted edits, branch + PR review, CI dry runs, and a safe path to onchain via Zodiac's review and signing UI.
+
+## Getting started
+
+This project starts with one example on Ethereum: a new Safe, a Roles mod on it, and a role that may wrap ETH and supply WETH to Aave.
+
+1. `npm install`.
+2. `npm run pull`. On first run, this opens a browser to authorize this directory and mint a Zodiac API key, which it writes to `.env`. It then fetches your org's users and accounts and the ABIs of the contracts in `zodiac.config.ts`, and generates types for them. If you don't have a Zodiac account yet, the browser walks you through sign-up first.
+   > `.env` is in `.gitignore`. Don't commit your API key.
+3. Edit `constellation/index.ts` and the role under `constellation/roles/treasury_ops/` to describe the state you want onchain. Start with the placeholder owner and member addresses.
+4. `npm run push`. This sends the constellation to Zodiac and opens a browser tab where you review the diff and sign the transactions.
+
+Day-to-day: edit the constellation, then `npm run push`. To permission another contract, add it to `zodiac.config.ts` under its chain prefix and run `npm run pull-contracts`, so the `allow` kit knows it.
+
+> **VS Code tip:** if `allow.eth.weth.*` (or whatever you just added) doesn't autocomplete after a pull, restart the TypeScript server: `Cmd+Shift+P` → "TypeScript: Restart TS Server".
+
+To check an edit without pushing, `npx zodiac push --dry-run` prints what would be pushed. It needs no API key.
+
+Using pnpm, yarn or Bun? Run the same scripts with `pnpm`, `yarn` or `bun run` in place of `npm run`.
+
+## Project layout
+
+```
+.
+├── constellation/
+│   ├── index.ts            # entrypoint — what gets pushed
+│   ├── allowances/         # reusable Roles-allowance objects
+│   └── roles/<role>/       # one folder per role
+│       ├── index.ts
+│       ├── members.ts      # addresses allowed to assume the role
+│       └── permissions.ts  # what the role can call
+├── zodiac.config.ts        # contracts the `allow` kit should know about
+├── abis/                   # contract ABIs, fetched by `npm run pull-contracts`
+├── .zodiac/                # generated codegen (git-ignored)
+└── .env                    # ZODIAC_API_KEY for this directory (git-ignored)
+```
+
+## Defining a constellation
+
+`constellation/index.ts` is what gets pushed to Zodiac. Start by scoping a constellation to a single workspace and chain:
+
+```ts
+import { constellation } from "@zodiaceco/sdk";
+
+const eth = constellation({
+  workspace: "Default workspace",
+  label: "Backend Operator",
+  chain: 1, // ethereum
+});
+```
+
+`npm run pull-org` regenerates type-level info for your workspace, so workspace name, chain id, account labels, role labels, and user handles all autocomplete.
+
+### Existing vs new nodes
+
+Bracket access on `.safe`, `.roles`, and `.user` is your editor for both **existing** accounts (vaults already in your workspace + anything previously pushed via a constellation) and **new** ones you're declaring for the first time.
+
+```ts
+// Reference an existing Safe verbatim — no invocation
+const treasury = eth.safe["GG Treasury"];
+
+// Tweak an existing Safe — invoke with overrides; all fields are optional
+export const tweaked = eth.safe["GG Treasury"]({ threshold: 4 });
+
+// Declare a new Safe — required fields are enforced at compile time
+export const backendSafe = eth.safe["Backend Safe"]({
+  nonce: 0n,
+  threshold: 2,
+  owners: ["0xcAF075b4102d96CdF9Bc5A2cEDb170a8b69697E8", eth.user["alice"]],
+  modules: [eth.roles["Backend Operator"]],
+});
+```
+
+For Safes the required fields are `nonce`, `threshold`, `owners`. For Roles mods, `nonce` (plus `owner`, `target`, `avatar` if you want anything other than the wired-up defaults). The SDK injects no runtime defaults — missing required fields surface as TypeScript errors.
+
+#### Binding to an existing Roles mod by address
+
+Bracket access only knows about accounts in your workspace codegen. To configure a Roles mod that's already deployed on-chain but **not** in your workspace, bind it by `address` instead of declaring a `nonce`. Zodiac diffs your spec against the live mod and updates only what changed:
+
+```ts
+const arb = constellation({
+  workspace: "Default workspace",
+  label: "Backend Operator",
+  chain: 42161, // arbitrum
+});
+
+export const ops = arb.roles["Existing roles mod"]({
+  address: "0x88A51CcB262d04B334065Ad425928dF79c4CB7d7",
+  roles: { backend_operator },
+});
+```
+
+A roles node therefore takes **either** `nonce` (deploy a new mod) **or** `address` (bind an existing one) — never both.
+
+### Forward references between new nodes
+
+New nodes can reference each other before either has been invoked — the uninvoked factory works as a forward reference. Both sides just need to be exported so `push()` resolves them by name:
+
+```ts
+export const backendSafe = eth.safe["Backend Safe"]({
+  nonce: 0n,
+  threshold: 2,
+  owners: ["0x1234567890123456789012345678901234567890"],
+  modules: [eth.roles["Backend Operator"]], // forward ref — not invoked yet
+});
+
+export const backendRoles = eth.roles["Backend Operator"]({
+  nonce: 0n,
+  target: backendSafe,
+  owner: backendSafe,
+  avatar: backendSafe,
+  roles: { backend_operator },
+  allowances: { usdc_payouts },
+});
+```
+
+### Users
+
+`eth.user["Alice Example"]` resolves to the user's personal Safe address on the constellation's chain. Useful in owner lists and role-member arrays without hardcoding addresses.
+
+### Pushing
+
+Only the values you `export` end up in the constellation.
+
+`npm run push` runs `pull` first, walks your exports, sends the spec to Zodiac, and opens your browser to review the diff and sign the transactions.
+
+### Roles and permissions
+
+Each role lives in its own folder under `constellation/roles/`:
+
+```
+constellation/roles/backend_operator/
+├── index.ts          # combines members + permissions
+├── members.ts        # who can act as this role
+└── permissions.ts    # what the role can call
+```
+
+Members are an array of addresses, user accessors, or node references — anything that resolves to an address is accepted:
+
+```ts
+import type { Members } from "@zodiaceco/sdk";
+
+export default [
+  "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  eth.user["alice"],
+  eth.safe["Trading Bot"],
+] satisfies Members;
+```
+
+A role's `permissions` is a list of **entries**. Each entry is one thing the role may do, and each carries a `label` that names it as a single card in the Zodiac UI — labels never reach the chain.
+
+```ts
+import { allow, type Permissions } from "@zodiaceco/sdk";
+import { custom, defikit, swap, transfer } from "@zodiaceco/sdk/actions";
+
+export default [
+  // A labelled bag of `allow`-kit permissions, for anything the
+  // other entries don't cover.
+  custom({
+    label: "Wrap and unwrap ETH",
+    permissions: [
+      allow.eth.weth.deposit({ send: true }),
+      allow.eth.weth.withdraw(),
+    ],
+  }),
+
+  // A DeFi Kit preset, by protocol and verb.
+  defikit.aave_v3.deposit({
+    label: "Supply WETH to Aave v3",
+    market: "Core",
+    targets: ["WETH"],
+  }),
+
+  // Sign CoW orders selling any of `sell` for any of `buy`.
+  swap({
+    label: "Rebalance stables",
+    sell: [USDC, DAI],
+    buy: [USDC, DAI],
+  }),
+
+  // Send tokens to fixed recipients, optionally bridged over Across.
+  transfer({
+    label: "Payouts",
+    tokens: [USDC],
+    to: [eth.safe["Payouts"]],
+    allowance: usdc_payouts,
+  }),
+] satisfies Permissions;
+```
+
+A bare `allow`-kit permission is still a valid entry — it just shows up unlabelled:
+
+```ts
+export default [allow.eth.weth.withdraw()] satisfies Permissions;
+```
+
+**Entries describe, they never compile.** A `defikit` entry stores its protocol, verb and parameters; a `swap` stores its token lists. The permissions are built when the constellation is deployed, so a stored revision always compiles through the current compilers instead of replaying a copy made when it was pushed. A compiled `PermissionSet` — what calling `defi-kit` directly returns — is therefore not an entry; reach for `defikit` instead.
+
+#### Allowances
+
+An allowance is a refilling budget the Roles modifier tracks on-chain. Define it once under `constellation/allowances/`, hand it to the roles node, and reference it from any permission that should draw on it:
+
+```ts
+// constellation/allowances/index.ts
+export const usdc_payouts = {
+  key: "usdc_payouts",
+  refill: 10_000n * 10n ** 6n, // added each period
+  maxRefill: 10_000n * 10n ** 6n, // cap the balance refills to
+  period: 60n * 60n * 24n, // seconds
+  balance: 10_000n * 10n ** 6n, // starting balance
+  timestamp: 0n,
+};
+```
+
+```ts
+// constellation/roles/<role>/permissions.ts
+import { allow, c } from "@zodiaceco/sdk";
+
+allow.eth.usdc.transfer(undefined, c.withinAllowance("usdc_payouts"));
+```
+
+A `key` is at most 31 bytes.
+
+#### Adding contracts
+
+The `allow` kit only knows about contracts listed in `zodiac.config.ts`. Add the address under the right chain prefix (see [Getting started](#getting-started) for an example), then run `npm run pull-contracts`. If a contract isn't verified on the explorer, the CLI prints the path where you should drop the ABI JSON by hand and re-run.
+
+#### Overloaded functions
+
+The `allow` kit names each member after its ABI function, so a contract that
+overloads a name — say sUSDS, with both `deposit(uint256,address)` and
+`deposit(uint256,address,uint16)` — has no single member that could mean either.
+Address the one you want by its full signature:
+
+```ts
+allow.eth.susds["deposit(uint256,address)"](
+  c.withinAllowance("sky_savings"),
+  c.avatar,
+);
+```
+
+## Commands
+
+| Command                  | What it does                                                                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `npm run pull`           | Refresh codegen: org data and contract ABIs. On first run, also authorizes this directory (mints an API key, writes `.env`).    |
+| `npm run pull-org`       | Just the org data (users, accounts)                                                                                             |
+| `npm run pull-contracts` | Just the contract ABIs and `allow` kit types. Run this after you add a contract to `zodiac.config.ts`.                          |
+| `npm run push`           | Send the constellation to Zodiac and open the review URL. Runs `pull` first, so you push against fresh org state and contracts. |
+| `npm run format`         | Prettier across the project                                                                                                     |

package/templates/constellation/_gitignore

@@ -0,0 +1,6 @@
+.env
+.DS_Store
+
+/node_modules
+/build
+/.zodiac

package/templates/constellation/abis/eth/weth.json

@@ -0,0 +1,153 @@
+[
+  {
+    "name": "name",
+    "type": "function",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "string" }],
+    "payable": false,
+    "constant": true,
+    "stateMutability": "view"
+  },
+  {
+    "name": "approve",
+    "type": "function",
+    "inputs": [
+      { "name": "guy", "type": "address" },
+      { "name": "wad", "type": "uint256" }
+    ],
+    "outputs": [{ "name": "", "type": "bool" }],
+    "payable": false,
+    "constant": false,
+    "stateMutability": "nonpayable"
+  },
+  {
+    "name": "totalSupply",
+    "type": "function",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "uint256" }],
+    "payable": false,
+    "constant": true,
+    "stateMutability": "view"
+  },
+  {
+    "name": "transferFrom",
+    "type": "function",
+    "inputs": [
+      { "name": "src", "type": "address" },
+      { "name": "dst", "type": "address" },
+      { "name": "wad", "type": "uint256" }
+    ],
+    "outputs": [{ "name": "", "type": "bool" }],
+    "payable": false,
+    "constant": false,
+    "stateMutability": "nonpayable"
+  },
+  {
+    "name": "withdraw",
+    "type": "function",
+    "inputs": [{ "name": "wad", "type": "uint256" }],
+    "outputs": [],
+    "payable": false,
+    "constant": false,
+    "stateMutability": "nonpayable"
+  },
+  {
+    "name": "decimals",
+    "type": "function",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "uint8" }],
+    "payable": false,
+    "constant": true,
+    "stateMutability": "view"
+  },
+  {
+    "name": "balanceOf",
+    "type": "function",
+    "inputs": [{ "name": "", "type": "address" }],
+    "outputs": [{ "name": "", "type": "uint256" }],
+    "payable": false,
+    "constant": true,
+    "stateMutability": "view"
+  },
+  {
+    "name": "symbol",
+    "type": "function",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "string" }],
+    "payable": false,
+    "constant": true,
+    "stateMutability": "view"
+  },
+  {
+    "name": "transfer",
+    "type": "function",
+    "inputs": [
+      { "name": "dst", "type": "address" },
+      { "name": "wad", "type": "uint256" }
+    ],
+    "outputs": [{ "name": "", "type": "bool" }],
+    "payable": false,
+    "constant": false,
+    "stateMutability": "nonpayable"
+  },
+  {
+    "name": "deposit",
+    "type": "function",
+    "inputs": [],
+    "outputs": [],
+    "payable": true,
+    "constant": false,
+    "stateMutability": "payable"
+  },
+  {
+    "name": "allowance",
+    "type": "function",
+    "inputs": [
+      { "name": "", "type": "address" },
+      { "name": "", "type": "address" }
+    ],
+    "outputs": [{ "name": "", "type": "uint256" }],
+    "payable": false,
+    "constant": true,
+    "stateMutability": "view"
+  },
+  { "type": "fallback", "payable": true, "stateMutability": "payable" },
+  {
+    "name": "Approval",
+    "type": "event",
+    "inputs": [
+      { "name": "src", "type": "address", "indexed": true },
+      { "name": "guy", "type": "address", "indexed": true },
+      { "name": "wad", "type": "uint256", "indexed": false }
+    ],
+    "anonymous": false
+  },
+  {
+    "name": "Transfer",
+    "type": "event",
+    "inputs": [
+      { "name": "src", "type": "address", "indexed": true },
+      { "name": "dst", "type": "address", "indexed": true },
+      { "name": "wad", "type": "uint256", "indexed": false }
+    ],
+    "anonymous": false
+  },
+  {
+    "name": "Deposit",
+    "type": "event",
+    "inputs": [
+      { "name": "dst", "type": "address", "indexed": true },
+      { "name": "wad", "type": "uint256", "indexed": false }
+    ],
+    "anonymous": false
+  },
+  {
+    "name": "Withdrawal",
+    "type": "event",
+    "inputs": [
+      { "name": "src", "type": "address", "indexed": true },
+      { "name": "wad", "type": "uint256", "indexed": false }
+    ],
+    "anonymous": false
+  }
+]

package/templates/constellation/constellation/allowances/index.ts

@@ -0,0 +1,4 @@
+// Refilling budgets the Roles mod tracks onchain, for permissions to draw on
+// with `c.withinAllowance("<key>")`. Add them to the Roles mod's
+// `allowances`. See "Allowances" in the README.
+export {};

package/templates/constellation/constellation/index.ts

@@ -0,0 +1,25 @@
+import { constellation } from "@zodiaceco/sdk";
+import { treasury_ops } from "./roles";
+
+const eth = constellation({
+  workspace: "Default workspace",
+  label: "Treasury",
+  chain: 1, // Ethereum
+});
+
+// A new Safe: replace the owner with your signers, then push.
+export const treasury = eth.safe["Treasury"]({
+  nonce: 0n,
+  threshold: 1,
+  owners: ["0x0000000000000000000000000000000000000001"],
+  modules: [eth.roles["Treasury Roles"]],
+});
+
+// A Roles mod on the Safe, holding the roles under `./roles`.
+export const treasuryRoles = eth.roles["Treasury Roles"]({
+  nonce: 0n,
+  target: treasury,
+  owner: treasury,
+  avatar: treasury,
+  roles: { treasury_ops },
+});

package/templates/constellation/constellation/roles/index.ts

@@ -0,0 +1 @@
+export * as treasury_ops from "./treasury_ops";

package/templates/constellation/constellation/roles/treasury_ops/index.ts

@@ -0,0 +1,2 @@
+export { default as members } from "./members";
+export { default as permissions } from "./permissions";

package/templates/constellation/constellation/roles/treasury_ops/members.ts

@@ -0,0 +1,4 @@
+import type { Members } from "@zodiaceco/sdk";
+
+// Who may act as this role: replace with your operators' addresses.
+export default ["0x0000000000000000000000000000000000000002"] satisfies Members;

package/templates/constellation/constellation/roles/treasury_ops/permissions.ts

@@ -0,0 +1,22 @@
+import { allow, type Permissions } from "@zodiaceco/sdk";
+import { custom, defikit } from "@zodiaceco/sdk/actions";
+
+// Each entry is one thing the role may do. Its label names it in the Zodiac
+// app and never reaches the chain.
+export default [
+  // `allow` kit permissions for the contracts in zodiac.config.ts.
+  custom({
+    label: "Wrap and unwrap ETH",
+    permissions: [
+      allow.eth.weth.deposit({ send: true }),
+      allow.eth.weth.withdraw(),
+    ],
+  }),
+
+  // A DeFi Kit preset, compiled when the constellation is deployed.
+  defikit.aave_v3.deposit({
+    label: "Supply WETH to Aave v3",
+    market: "Core",
+    targets: ["WETH"],
+  }),
+] satisfies Permissions;

package/templates/constellation/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "zodiac-constellation",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "format": "prettier --write .",
+    "pull": "zodiac pull",
+    "pull-org": "zodiac pull-org",
+    "pull-contracts": "zodiac pull-contracts",
+    "push": "zodiac pull && zodiac push"
+  },
+  "dependencies": {
+    "@zodiaceco/sdk": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "prettier": "^3.6.2",
+    "typescript": "^5"
+  }
+}

package/templates/constellation/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    // "incremental": true,                   /* Enable incremental compilation */
+    "target": "esnext" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */,
+    "module": "esnext" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */,
+    "strict": true /* Enable all strict type-checking options. */,
+    "moduleResolution": "bundler" /* Respect package.json `exports` subpaths (required for @zodiaceco/sdk/allow etc). */,
+    "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true /* Disallow inconsistently-cased references to the same file. */,
+    "typeRoots": ["./node_modules/@types"],
+    "lib": ["ES2023"]
+  },
+  "include": ["constellation/**/*", "zodiac.config.ts", ".zodiac/**/*"]
+}

package/templates/constellation/zodiac.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "@zodiaceco/sdk/cli/config";
+
+// The contracts the `allow` kit knows, by chain prefix. After changing them,
+// run `npm run pull-contracts` to fetch their ABIs into `abis/`.
+export default defineConfig({
+  contracts: {
+    eth: {
+      weth: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    },
+  },
+});