@tula-tech/cli 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,8 @@
 
 The `tula` command line for [Tula Auth](../../README.md): `tula dev` (the local stack),
 `tula doctor` (check a deployment), `tula policy test` (try a password against a policy),
-`tula mcp` (the MCP server, [docs/mcp.md](../../docs/mcp.md)), and
+`tula import` (move users, with their password hashes, from Clerk, Auth0, Firebase, Supabase or
+better-auth), `tula mcp` (the MCP server, [docs/mcp.md](../../docs/mcp.md)), and
 `tula diff` / `tula apply`, which keep an environment's settings and OAuth providers in step
 with a `tula.config.ts`. Every command is in [docs/cli.md](../../docs/cli.md); settings as code
 in [docs/config.md](../../docs/config.md); the decisions in
@@ -45,4 +46,90 @@ https (or localhost; `--insecure-http` for a private network you trust).
 `tula` runs on **Bun** (`#!/usr/bin/env bun`): the first thing every command does is import
 the project's `tula.config.ts`, which Bun runs as it is.
 
+## Commands
+
+| Command | What |
+| --- | --- |
+| `tula dev` | Start the local stack of a project `create-tula` made: Compose, migrations, seed, development keys. |
+| `tula dev down` | Stop it; the data is kept. `--volumes` also deletes the database (asks first). |
+| `tula doctor` | Check a deployment, each problem with its fix. `--strict` fails on a warning, `--json` is for a pipeline. |
+| `tula policy test` | Which rules of an environment's password policy a password passes. |
+| `tula mcp` | The MCP server an AI assistant reads and proposes through, on standard input and output. |
+| `tula approve <id>` | Approve a change an assistant proposed, after showing what it does. |
+| `tula import --from <provider> <file>` | Move users, with their password hashes, from Clerk, Auth0, Firebase, Supabase or better-auth. Prints a report; `--yes` imports. |
+| `tula audit export` | Stream the audit log as NDJSON or CSV (`--format`, `--from`, `--to`, `--action`, `--organization`, `--resume`). |
+| `tula diff`, `tula apply` | Settings as code: compare, then change an environment to match `tula.config.ts`. |
+
+```sh
+tula dev                       # start, or continue; running it again changes nothing
+tula dev --tunnel              # the same stack at a public https address a phone can reach
+tula doctor --strict
+printf %s "$PW" | tula policy test --env prod --email maya@example.com
+tula import --from supabase supabase-users.csv          # a report; nothing is sent
+tula import --from supabase supabase-users.csv --yes
+tula audit export --from 2026-01-01 --to 2026-02-01 > january.ndjson
+```
+
+Options shared by the commands that talk to an API: `--env <name>`, `--api-url <url>`,
+`--insecure-http` and `--secret-key-file <path>`. `tula apply` also takes `--yes`,
+`--prune`, `--allow-weaker`, `--allow-unknown` and `--allow-webhook-removal`; a run that
+creates a webhook endpoint needs `--secrets-file`, `--show-secrets` or `--discard-secrets` to
+say what happens to its signing secret. Exit codes differ per command and are listed with each
+in [docs/cli.md](../../docs/cli.md).
+
+## Credentials are never arguments
+
+A command line is kept in shell history and shows in process lists, so no option takes a
+secret: `--secret-key`, `--admin-token` and `--password` do not exist.
+
+| What | Where it comes from |
+| --- | --- |
+| API URL | `--api-url`, else `TULA_API_URL_<NAME>` (with `--env <name>`), else `TULA_API_URL`. |
+| Secret key | `TULA_SECRET_KEY_<NAME>`, else `TULA_SECRET_KEY`, or `--secret-key-file <path>`. |
+| Agent key (`tula mcp` only) | `TULA_AGENT_KEY_<NAME>`, else `TULA_AGENT_KEY`, or `--agent-key-file <path>`. |
+| Instance admin token | `TULA_ADMIN_TOKEN`, or `--admin-token-file <path>` (`-` for a pipe). |
+
+Bun loads `.env` and `.env.local` from the current directory, so in a project made by
+[`create-tula`](../create-tula/README.md) the URL and keys `tula dev` wrote are found with
+nothing exported.
+
+## Security notes
+
+- The API URL must be https, or this machine; `--insecure-http` is for a private network you
+  trust.
+- `tula policy test` evaluates the rules on your machine: the password is never sent, printed
+  or logged. `tula import` reads the provider's export locally, prints no hash, token or whole
+  address, and keeps its progress file at mode `0600` with no hash in it.
+- `tula dev` writes keys to `.env.local` at mode `0600` and prints the secret key only with
+  `--show-keys`.
+- `tula mcp` with an agent key does not read the secret key at all.
+- The CLI never connects to your database; `tula doctor` asks the API.
+
+## Requirements
+
+[Bun](https://bun.sh) 1.2 or later (`engines.bun`). The executable is `#!/usr/bin/env bun`,
+and every command imports the project's `tula.config.ts` as it is. `tula dev` also needs
+Docker with Compose.
+
+## Running it
+
+| Where | How |
+| --- | --- |
+| A project, after `bun add -d @tula-tech/cli@latest` | `bunx tula <command>` |
+| Anywhere else | `bunx --package @tula-tech/cli@latest tula <command>` |
+| This repository | `bun run tula -- <command>` |
+
+In CI, install the package as a dev dependency and call `tula diff --env prod` as a check
+(exit 2 means the file and the environment disagree) before `tula apply --env prod --yes`.
+Keep the secret key in the CI system's secret store and pass it as `TULA_SECRET_KEY_PROD`.
+
+## Learn more
+
+- [docs/cli.md](../../docs/cli.md): every command, option and exit code.
+- [docs/config.md](../../docs/config.md): `tula.config.ts`, `diff` and `apply`.
+- [docs/mcp.md](../../docs/mcp.md): the MCP server and `tula approve`.
+- [docs/quickstart.md](../../docs/quickstart.md): a project of your own.
+
+## Contributing
+
 A new command is one object of the `Command` shape added to `COMMANDS` in `src/index.ts`.

package/dist/bin.js

@@ -2,7 +2,7 @@
 // @bun
 import {
   main2
-} from "./shared/chunk-4x7xmfqj.js";
+} from "./shared/chunk-erqwg4v0.js";
 
 // src/bin.ts
 process.exit(await main2(process.argv.slice(2)));

package/dist/index.d.ts

@@ -57,7 +57,7 @@ interface ParsedArgs {
 * @param argv - The arguments after the command's name.
 * @param options - The options the command takes, by name.
 * @returns The options that were given and the positional arguments.
-* @throws UsageError for an unknown option, a missing value, or a value given to a flag.
+* @throws UsageError for an unknown option, a missing value, a value given to a flag, or an option given twice.
 *
 * @example
 * ```ts
@@ -500,6 +500,16 @@ declare const applyCommand: Command;
 */
 declare const approveCommand: Command;
 /**
+* `tula audit export`: the environment's audit log to standard output, oldest first, as
+* NDJSON or CSV, streamed and resumable.
+*
+* @example
+* ```sh
+* tula audit --format csv --from 2026-01-01 > audit.csv
+* ```
+*/
+declare const auditCommand: Command;
+/**
 * `tula dev`: start the project's local stack with Docker Compose, migrate, seed, mint
 * development keys into `.env.local` and print the URLs. `tula dev down` stops it.
 * `--tunnel` also gives the stack a public https address (ADR 0049).
@@ -536,6 +546,20 @@ declare const diffCommand: Command;
 * ```
 */
 declare const doctorCommand: Command;
+/**
+* `tula import`: move users from another provider. It reads the provider's own on this
+* machine (no request to the old provider), prints a dry-run report, and with `--yes` imports
+* the users through `POST /v1/admin/users/import` in batches, keeping a progress file so that an
+* interrupted run continues where it stopped. A Clerk export's organizations and memberships go
+* through the organization admin routes.
+*
+* @example
+* ```sh
+* tula import --from supabase users.csv          # dry run: a report, nothing sent
+* tula import --from supabase users.csv --yes    # import; run again after an interruption
+* ```
+*/
+declare const importCommand: Command;
 import { McpServer as McpServer_ymih5p } from "@modelcontextprotocol/server";
 /**
 * Build the MCP server `tula mcp` serves, from the same places every other command reads its
@@ -712,6 +736,7 @@ declare function withoutDevBlock(text: string): string;
 * @param text - The file's contents (`''` for a new file).
 * @param vars - The block's variables.
 * @returns The new contents.
+* @throws UsageError when a name is not `NAME_LIKE` or a value holds a control character.
 *
 * @example
 * ```ts
@@ -796,7 +821,7 @@ declare function stopDev(options: Pick<DevOptions, "io" | "output" | "host" | "p
 	volumes: boolean;
 }): Promise<void>;
 import { AdminSchemas } from "@tula-tech/admin";
-import { EnvironmentConfig, NativeAppConfig } from "@tula-tech/config";
+import { EnvironmentConfig, NativeAppConfig, OrganizationRoleConfig } from "@tula-tech/config";
 import { EnvironmentSettings, EnvironmentSettingsInput, HookPoint, OAuthProvider, SettingsManagedBy } from "@tula-tech/contract";
 /**
 * The name `tula apply` records itself under as the manager of an environment's settings.
@@ -912,6 +937,16 @@ interface RemoteState {
 	* are then not even read.
 	*/
 	nativeApps?: readonly RemoteNativeApp[];
+	/**
+	* The organization roles, built-in ones included. Left out when the config does not manage
+	* roles: they are then not even read.
+	*/
+	organizationRoles?: readonly RemoteOrganizationRole[];
+	/**
+	* Set when the roles could not be read because organizations are off on the server: custom
+	* roles may exist that the plan does not know of.
+	*/
+	organizationRolesUnread?: boolean;
 }
 /**
 * A native app as the admin API lists it.
@@ -998,6 +1033,82 @@ interface NativeAppPlan {
 	seen: string;
 }
 /**
+* A custom organization role as the admin API lists it (the built-in roles are listed too and
+* are never planned: `builtIn`).
+*
+* @example
+* ```ts
+* const { data } = await admin.call('listOrganizationRoles')
+* const roles: RemoteOrganizationRole[] = data.data
+* ```
+*/
+type RemoteOrganizationRole = AdminSchemas["OrganizationRole"];
+/**
+* What a run does with one custom organization role.
+*
+* @example
+* ```ts
+* const change: OrganizationRoleChange = planOrganizationRoles(remote.organizationRoles, environment.organizationRoles, {}).roles[0]
+* ```
+*/
+interface OrganizationRoleChange {
+	/** The role's key: its identity, the file's for an entry of the file, the server's otherwise. */
+	key: string;
+	/** The server's id of the role. Absent for one to create. */
+	id?: string;
+	/**
+	* The role's version as the plan read it: the `If-Match` of the update or delete that
+	* follows, so that a change made after the plan is refused by the server (412) and never
+	* written over. Absent for a role to create.
+	*/
+	version?: number;
+	/**
+	* `create`, `update`, `delete`; `none` when it already is as the config says; `unmanaged`
+	* when the server has it and the config does not list it (left alone without `--prune`).
+	*/
+	action: "create" | "update" | "delete" | "none" | "unmanaged";
+	/**
+	* The differences: `name`, and `permissions` as a set (`added`, `removed`). For a role to
+	* create, what it is defined with.
+	*/
+	fields: Change[];
+	/**
+	* `organizationRoles.<key>.permissions` when the change gives members of the role a
+	* permission it did not have, as the contract's `organizationRoleWeakenings` judges it.
+	* Part of the plan's `weakened`. A new role is no weakening: nobody holds it.
+	*/
+	weakened: string[];
+	/** The config's entry, for a role the run creates or updates: what the write sends. */
+	entry?: OrganizationRoleConfig;
+}
+/**
+* What a run does with an environment's custom organization roles.
+*
+* @example
+* ```ts
+* if (plan.organizationRoles.overLimit !== null) {
+*   // the environment would have more custom roles than it may
+* }
+* ```
+*/
+interface OrganizationRolePlan {
+	/** Whether the config has an `organizationRoles` list at all. Without one nothing is read or changed. */
+	managed: boolean;
+	/** One entry per role of the file, in its order, then the server's other custom roles. */
+	roles: OrganizationRoleChange[];
+	/**
+	* How many custom roles the environment would have once the plan is applied, when that is
+	* more than it may have (`MAX_CUSTOM_ROLES`); `null` otherwise.
+	*/
+	overLimit: number | null;
+	/**
+	* The server's roles could not be read (organizations are off there), so every listed role
+	* is planned as a definition. A role that exists makes that definition fail with
+	* `organization.role_exists`, writing nothing over it; `tula diff` again then shows it.
+	*/
+	unread: boolean;
+}
+/**
 * A hook as the admin API lists it. Never with its signing secret: no read returns one.
 *
 * @example
@@ -1351,7 +1462,8 @@ interface Plan {
 	* Paths where the run weakens security: the settings' (the contract's
 	* `settingsWeakenings`), then the providers' (`oauthProviderWeakenings`, as
 	* `providers.<provider>…`), then the hooks' (`hookWeakenings`, as `hooks.<point>…`), then the
-	* native apps' (`nativeAppWeakenings`, as `nativeApps.<platform>/<identifier>…`).
+	* native apps' (`nativeAppWeakenings`, as `nativeApps.<platform>/<identifier>…`), then the
+	* organization roles' (`organizationRoleWeakenings`, as `organizationRoles.<key>.permissions`).
 	*/
 	weakened: string[];
 	/** Settings the file leaves out whose default is the deployment's: kept as the server has them. */
@@ -1366,6 +1478,8 @@ interface Plan {
 	hooks: HookPlan;
 	/** What happens to each native app, when the config manages them. */
 	nativeApps: NativeAppPlan;
+	/** What happens to each custom organization role, when the config manages them. */
+	organizationRoles: OrganizationRolePlan;
 	/** Whether the server records this config as the settings' manager. */
 	marker: MarkerPlan;
 	/** The document a replace would send. */
@@ -1455,6 +1569,22 @@ type Operation = {
 	kind: "nativeApp.delete";
 	id: string;
 	change: NativeAppChange;
+} | {
+	kind: "organizationRole.create";
+	key: string;
+	entry: OrganizationRoleConfig;
+	change: OrganizationRoleChange;
+} | {
+	kind: "organizationRole.update";
+	key: string;
+	version: number;
+	entry: OrganizationRoleConfig;
+	change: OrganizationRoleChange;
+} | {
+	kind: "organizationRole.delete";
+	key: string;
+	version: number;
+	change: OrganizationRoleChange;
 };
 /**
 * The writes of a plan, in an order in which every intermediate state is one the server
@@ -1499,6 +1629,13 @@ type Operation = {
 * that widen nothing (a fingerprint or a link path taken away), then changes that widen
 * (another team, a gained fingerprint, a gained link path), then registrations.
 *
+* **Custom organization roles come after the native apps.** The settings that switch
+* organizations on are written first, and a role's write is refused while they are off. Among
+* themselves, as the native apps' and for the same reasons: removals, then changes that give
+* a role nothing (a permission taken away, a rename), then changes that give it a permission,
+* then definitions, so that the limit (`MAX_CUSTOM_ROLES`) is never met on the way to a state
+* that fits and a run that stops has widened as little as it could.
+*
 * @param plan - The plan.
 * @returns The writes, in order; empty when the plan changes nothing.
 *
@@ -1688,7 +1825,8 @@ declare function applyRequirements(plan: Plan): {
 *
 * @param operation - The write.
 * @returns E.g. `settings: replace`, `provider google: create`, `webhook https://…: remove`,
-*   `hook before_sign_up: update`, `native app ios com.example.app: register`.
+*   `hook before_sign_up: update`, `native app ios com.example.app: register`,
+*   `organization role billing_manager: define`.
 *
 * @example
 * ```ts
@@ -1746,6 +1884,13 @@ interface Target {
 	apiUrl: string;
 	/** The admin client, holding the secret key. */
 	admin: AdminClient;
+	/**
+	* Tells this API and key from another without holding either: 16 hex characters of a SHA-256
+	* of the origin and the key. A progress file is bound to it (`tula import`).
+	*/
+	fingerprint: string;
+	/** The key's kind and environment as it names itself (`secret key, dev`), for a prompt. */
+	keyLabel: string;
 }
 /**
 * Work out which API a run talks to and with which key.
@@ -1868,10 +2013,10 @@ declare function resolveInstance(input: {
 *
 * @example
 * ```ts
-* `tula-cli/${VERSION}` // 'tula-cli/0.2.0'
+* `tula-cli/${VERSION}` // 'tula-cli/0.3.0'
 * ```
 */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.0";
 /**
 * The commands of `tula`. A new command is added here.
 *
@@ -1895,4 +2040,4 @@ declare const COMMANDS: readonly Command[];
 * ```
 */
 declare function main(argv: readonly string[], overrides?: Partial<CliIo>): Promise<number>;
-export { COMMANDS, Change, CheckStatus, CliIo, Command, CommandContext, DEPENDENTS_UNREAD, DEV_ENV_FILE, DependentCount, DevOptions, DoctorCheck, DoctorReport, EXIT, Host, KnownDependents, MANAGING_TOOL, MarkerPlan, Operation, OptionSpec, Output, ParsedArgs, Plan, PlanOptions, ProviderChange, RemoteDependents, RemoteProvider, RemoteState, RunOptions, RunResult, SET_PATHS, Sink, Styles, Target, UsageError, VERSION, applyCommand, applyRequirements, approveCommand, buildMcpServer, buildPlan, createOutput, describeOperation, devCommand, diffCommand, diffValues, doctorCommand, examine, exitCode, main, mcpCommand, orderOperations, parseArgs, parseDevBlock, planProviders, planToJson, planWarnings, policyCommand, printable, providersGoingOff, readDependentCount, readSecretFile, renderPlan, renderReport, reportError, reportToJson, resolveAgent, resolveApiUrl, resolveInstance, resolveTarget, runCli, shouldUseColor, startDev, stopDev, withDevBlock, withoutDevBlock };
+export { COMMANDS, Change, CheckStatus, CliIo, Command, CommandContext, DEPENDENTS_UNREAD, DEV_ENV_FILE, DependentCount, DevOptions, DoctorCheck, DoctorReport, EXIT, Host, KnownDependents, MANAGING_TOOL, MarkerPlan, Operation, OptionSpec, Output, ParsedArgs, Plan, PlanOptions, ProviderChange, RemoteDependents, RemoteProvider, RemoteState, RunOptions, RunResult, SET_PATHS, Sink, Styles, Target, UsageError, VERSION, applyCommand, applyRequirements, approveCommand, auditCommand, buildMcpServer, buildPlan, createOutput, describeOperation, devCommand, diffCommand, diffValues, doctorCommand, examine, exitCode, importCommand, main, mcpCommand, orderOperations, parseArgs, parseDevBlock, planProviders, planToJson, planWarnings, policyCommand, printable, providersGoingOff, readDependentCount, readSecretFile, renderPlan, renderReport, reportError, reportToJson, resolveAgent, resolveApiUrl, resolveInstance, resolveTarget, runCli, shouldUseColor, startDev, stopDev, withDevBlock, withoutDevBlock };

package/dist/index.js

@@ -34,6 +34,7 @@ import {
   resolveInstance2,
   applyCommand2,
   approveCommand2,
+  auditCommand2,
   DEV_ENV_FILE2,
   parseDevBlock2,
   withoutDevBlock2,
@@ -43,12 +44,13 @@ import {
   devCommand2,
   diffCommand2,
   doctorCommand2,
+  importCommand2,
   buildMcpServer2,
   mcpCommand2,
   policyCommand2,
   COMMANDS2,
   main2
-} from "./shared/chunk-4x7xmfqj.js";
+} from "./shared/chunk-erqwg4v0.js";
 export {
   COMMANDS2 as COMMANDS,
   DEPENDENTS_UNREAD2 as DEPENDENTS_UNREAD,
@@ -61,6 +63,7 @@ export {
   applyCommand2 as applyCommand,
   applyRequirements2 as applyRequirements,
   approveCommand2 as approveCommand,
+  auditCommand2 as auditCommand,
   buildMcpServer2 as buildMcpServer,
   buildPlan2 as buildPlan,
   createOutput2 as createOutput,
@@ -71,6 +74,7 @@ export {
   doctorCommand2 as doctorCommand,
   examine2 as examine,
   exitCode2 as exitCode,
+  importCommand2 as importCommand,
   main2 as main,
   mcpCommand2 as mcpCommand,
   orderOperations2 as orderOperations,