@grantjs/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Heredia
+
+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.md

@@ -0,0 +1,150 @@
+# @grantjs/cli
+
+Grant CLI for setup, authentication, profiles, and typings generation.
+
+## Install
+
+```bash
+pnpm add -g @grantjs/cli
+# or
+npm install -g @grantjs/cli
+```
+
+## Commands overview
+
+| Command                       | Description                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------------------- |
+| `grant version`               | Show CLI version (`-j, --json` for JSON)                                                       |
+| `grant help` / `grant --help` | Show help                                                                                      |
+| `grant start`                 | Interactive setup (API URL, auth, profile, scope); alias: `grant setup`                        |
+| `grant generate-types`        | Generate project-scoped `ResourceSlug` and `ResourceAction` TypeScript (uses selected profile) |
+| `grant config path`           | Print path to the config file                                                                  |
+| `grant config list`           | List profiles and which is default                                                             |
+| `grant config show`           | Show config summary for a profile (no secrets)                                                 |
+| `grant config set <key>`      | Set a config value for a profile (see below)                                                   |
+
+All commands that use config accept **`-p, --profile <name>`** to target a profile (default: the configured default profile).
+
+---
+
+## Setup: `grant start`
+
+Interactive flow:
+
+1. **Grant API base URL** – Default: `http://localhost:4000` (or existing value).
+2. **Authentication method** – **Session** (browser login) or **API key**.
+3. **Profile name** – Name for this config (e.g. `default`, `staging`). Override with `--profile <name>` to skip the prompt.
+4. **Session flow** – Sign in with **Email** (email + password) or **GitHub** (browser OAuth). Then choose account → organization (if applicable) → project.
+5. **API key flow** – Client ID (UUID), client secret (min 32 chars), scope tenant (`accountProject` / `organizationProject`), scope ID (e.g. `accountId:projectId` or `organizationId:projectId`).
+6. **Default output for generate-types** – Optional path (e.g. `./src/grant-types.ts`). Leave empty for `./grant-types.ts`.
+
+Config is saved to the platform config dir (e.g. `~/.config/grant/config.json` on Linux/macOS). The first profile created becomes the default; change it with `grant config set default-profile <name>`.
+
+### Session authentication
+
+- **Email** – You are prompted for email and password; the CLI calls the Grant API login endpoint and stores the returned access and refresh tokens.
+- **GitHub** – The CLI starts a temporary local HTTP server and opens your browser to the Grant API’s GitHub OAuth URL with a `redirect` to `http://localhost:<port>`. After you sign in with GitHub, the API redirects back to that URL with a one-time code. The CLI exchanges the code for access and refresh tokens via `POST /api/auth/cli-callback`. No tokens are sent in the URL; the code is single-use and short-lived (e.g. 60 seconds). The API only accepts `localhost` (or `127.0.0.1`) as the redirect for this flow.
+
+**Examples:**
+
+```bash
+grant start
+grant start --profile staging
+```
+
+---
+
+## Generate types: `grant generate-types`
+
+Loads the selected profile, exchanges API key for a token if needed, fetches resources and permissions for the project scope, and writes a TypeScript file with `ResourceSlug` and `ResourceAction` constants.
+
+- **`-o, --output <path>`** – Output file (default: profile’s `generateTypesOutputPath` or `./grant-types.ts`).
+- **`--dry-run`** – Print what would be generated without writing.
+- **`-p, --profile <name>`** – Profile to use (default: default profile).
+
+**Examples:**
+
+```bash
+grant generate-types
+grant generate-types --profile staging -o ./src/grant-types.ts
+grant generate-types --dry-run
+```
+
+---
+
+## Config: `grant config`
+
+### `grant config path`
+
+Prints the path to the config file (no profile).
+
+### `grant config list`
+
+Lists profile names and marks the default.
+
+### `grant config show`
+
+Shows config summary for a profile (API URL, auth method, scope, generate-types output; no secrets).
+
+- **`-p, --profile <name>`** – Profile to show (default: default profile).
+
+### `grant config set`
+
+Set a value for a profile. Use **`-p, --profile <name>`** to target a profile (default: default profile).
+
+| Subcommand                                          | Description                                                         |
+| --------------------------------------------------- | ------------------------------------------------------------------- |
+| `grant config set api-url <url>`                    | Set Grant API base URL (e.g. `http://localhost:4000`)               |
+| `grant config set auth-method <session \| api-key>` | Set authentication method                                           |
+| `grant config set credentials`                      | Set API key and scope (see options below)                           |
+| `grant config set scope`                            | Set selected project scope only                                     |
+| `grant config set generate-types-output <path>`     | Set default output path for `grant generate-types` (empty to clear) |
+| `grant config set default-profile <name>`           | Set which profile is used when `--profile` is omitted               |
+
+**Credentials options** (all required for `credentials`):
+
+- `--client-id <id>` – API key client ID (UUID)
+- `--client-secret <secret>` – API key client secret (min 32 characters)
+- `--scope-tenant <tenant>` – `accountProject` or `organizationProject`
+- `--scope-id <id>` – e.g. `accountId:projectId` or `organizationId:projectId`
+
+**Scope options** (for `scope`):
+
+- `--tenant <tenant>` – `accountProject` or `organizationProject`
+- `--scope-id <id>` – Scope ID string
+
+**Examples:**
+
+```bash
+grant config set api-url http://localhost:4000
+grant config set api-url http://localhost:4000 --profile staging
+grant config set credentials --client-id <uuid> --client-secret <secret> --scope-tenant organizationProject --scope-id <orgId>:<projectId>
+grant config set scope --tenant organizationProject --scope-id <orgId>:<projectId>
+grant config set generate-types-output ./src/grant-types.ts
+grant config set default-profile staging
+```
+
+---
+
+## Development (from monorepo)
+
+```bash
+pnpm --filter @grantjs/cli run build
+node packages/@grantjs/cli/dist/index.mjs version
+# or link globally: from packages/@grantjs/cli run pnpm link --global
+```
+
+**Interactive TUI:** Run `grant start` (and any prompts) in a real terminal so the process has a TTY. Running via IDE "Run" or in CI often has no stdin and prompts will not work.
+
+**Documentation:** [Grant CLI](https://github.com/logusgraphics/grant/blob/main/docs/integration/cli.md) in the official docs.
+
+**Publishing:** See [RELEASE.md](./RELEASE.md) for versioning and npm publish (Changesets).
+
+**Tests:**
+
+```bash
+pnpm --filter @grantjs/cli test
+pnpm --filter @grantjs/cli test:watch
+```
+
+---

package/dist/api/client.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Minimal REST client for Grant API.
+ * Used by start (token exchange) and generate-types (resources/permissions).
+ */
+export interface TokenExchangeScope {
+    id: string;
+    tenant: string;
+}
+export interface TokenExchangeRequest {
+    clientId: string;
+    clientSecret: string;
+    scope: TokenExchangeScope;
+}
+export interface TokenExchangeResponse {
+    accessToken: string;
+    expiresIn: number;
+}
+export interface ApiErrorBody {
+    success?: false;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+    reason?: string;
+    code?: string;
+}
+export interface LoginAccount {
+    id: string;
+    type: string;
+    ownerId: string | null;
+    [key: string]: unknown;
+}
+export interface LoginResult {
+    /** Primary account (personal or first). */
+    account: LoginAccount;
+    /** All user accounts from login (personal + organization). Use for account selector. */
+    accounts: LoginAccount[];
+    accessToken: string;
+    refreshToken: string;
+}
+export interface OrganizationItem {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+export interface ProjectItem {
+    id: string;
+    name: string;
+    slug: string;
+    [key: string]: unknown;
+}
+/**
+ * Exchange API key (clientId + clientSecret) for an access token.
+ * POST {baseUrl}/api/auth/token
+ */
+export declare function exchangeApiKey(baseUrl: string, body: TokenExchangeRequest): Promise<TokenExchangeResponse>;
+/**
+ * Login with email and password. POST {baseUrl}/api/auth/login
+ * Returns access token, refresh token, and primary account (personal).
+ */
+export declare function loginWithEmail(baseUrl: string, email: string, password: string): Promise<LoginResult>;
+/**
+ * Exchange one-time CLI OAuth code for session. POST {baseUrl}/api/auth/cli-callback
+ * Used after browser redirect from GitHub OAuth when redirect_uri was localhost.
+ */
+export declare function exchangeCliCallback(baseUrl: string, code: string): Promise<LoginResult>;
+/**
+ * Fetch organizations (paginated). Requires Bearer token. GET /api/organizations?scopeId=&tenant=
+ * Scope is the account context (user's personal account id, tenant 'account').
+ */
+export declare function fetchOrganizations(baseUrl: string, accessToken: string, scope: ApiScope): Promise<OrganizationItem[]>;
+/**
+ * Fetch projects for a scope (account or organization). Paginated. Requires Bearer token.
+ * GET /api/projects?scopeId=&tenant=
+ */
+export declare function fetchProjects(baseUrl: string, accessToken: string, scope: ApiScope): Promise<ProjectItem[]>;
+export interface ApiScope {
+    id: string;
+    tenant: string;
+}
+export interface ResourceItem {
+    id: string;
+    slug: string;
+    name: string;
+    actions: string[];
+    [key: string]: unknown;
+}
+export interface PermissionItem {
+    id: string;
+    action: string;
+    name: string;
+    [key: string]: unknown;
+}
+/**
+ * Fetch all resources for a scope (paginated). Requires Bearer token.
+ */
+export declare function fetchResources(baseUrl: string, accessToken: string, scope: ApiScope): Promise<ResourceItem[]>;
+/**
+ * Fetch all permissions for a scope (paginated). Requires Bearer token.
+ */
+export declare function fetchPermissions(baseUrl: string, accessToken: string, scope: ApiScope): Promise<PermissionItem[]>;

package/dist/commands/config-cmd.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createConfigCommand(program: Command): void;

package/dist/commands/generate-types-impl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generate TypeScript content for ResourceSlug and ResourceAction from project data.
+ * Mirrors the shape of @grantjs/constants permissions/resources.ts.
+ */
+/** Convert slug (e.g. "user-documents") or action (e.g. "Create") to PascalCase key. */
+export declare function toPascalCase(s: string): string;
+/**
+ * Generate the TypeScript file content for ResourceSlug and ResourceAction.
+ * - slugs: unique resource slugs from the project (e.g. from GET /api/resources).
+ * - actions: unique permission actions from the project (e.g. from GET /api/permissions).
+ */
+export declare function generateTypesContent(slugs: string[], actions: string[]): string;

package/dist/commands/generate-types.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createGenerateTypesCommand(program: Command): void;

package/dist/commands/start.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createStartCommand(program: Command): void;

package/dist/commands/version.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createVersionCommand(program: Command): void;

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_PROFILE_NAME, getConfigDir, getConfigPath, getProfileConfig, listProfileNames, loadConfig, loadConfigFile, loadProfile, resolveProfileName, saveConfigFile, } from './storage.js';
+export { resolveAccessToken } from './resolve-token.js';
+export type { ApiKeyCredentials, GrantConfig, GrantConfigFile, GrantScope, ProfileName, SessionCredentials, } from '../types/config.js';

package/dist/config/resolve-token.d.ts

@@ -0,0 +1,9 @@
+import { GrantConfig } from '../types/config.js';
+/**
+ * Resolve a valid access token from stored config.
+ * Only tokens are stored (no credentials). Session auth does not auto-refresh; user must re-auth when the access token expires.
+ *
+ * - API key: exchanges clientId + clientSecret for a fresh token (no credentials stored after exchange).
+ * - Session: returns the stored access token. When it expires, the user must run "grant start" again to re-authenticate.
+ */
+export declare function resolveAccessToken(config: GrantConfig): Promise<string>;

package/dist/config/storage.d.ts

@@ -0,0 +1,49 @@
+import { GrantConfig, GrantConfigFile } from '../types/config.js';
+declare const DEFAULT_PROFILE_NAME = "default";
+/**
+ * Returns the platform-specific config directory for Grant CLI.
+ * - Windows: %APPDATA%\grant
+ * - Linux/macOS: $XDG_CONFIG_HOME/grant or ~/.config/grant
+ */
+export declare function getConfigDir(): string;
+/**
+ * Returns the path to the config file (config dir + config.json).
+ */
+export declare function getConfigPath(): string;
+/**
+ * Load config file from disk. Migrates legacy single-config to profiles shape.
+ * Returns null if file does not exist or is invalid.
+ */
+export declare function loadConfigFile(): Promise<GrantConfigFile | null>;
+/**
+ * Save config file to disk. Creates config dir if needed. Sets file mode to 0o600 (owner read/write only).
+ */
+export declare function saveConfigFile(file: GrantConfigFile): Promise<void>;
+/**
+ * Resolve which profile name to use: explicit name, or file's default, or "default".
+ */
+export declare function resolveProfileName(file: GrantConfigFile, profileFlag: string | undefined): string;
+/**
+ * Get config for a profile. Returns null if profile does not exist.
+ */
+export declare function getProfileConfig(file: GrantConfigFile, profileName: string): GrantConfig | null;
+/**
+ * List profile names. Returns empty array if no file.
+ */
+export declare function listProfileNames(file: GrantConfigFile | null): string[];
+/** Default profile name constant for use in prompts/help. */
+export { DEFAULT_PROFILE_NAME };
+/**
+ * Load config file and return the default profile's config.
+ * Convenience for callers that only need one profile (default). Returns null if no file or default profile missing.
+ */
+export declare function loadConfig(): Promise<GrantConfig | null>;
+/**
+ * Load config file and return the resolved profile's config plus file and name.
+ * Use when you need to read and then update (save) the file. Returns null if no file or profile does not exist.
+ */
+export declare function loadProfile(profileFlag?: string): Promise<{
+    file: GrantConfigFile;
+    config: GrantConfig;
+    profileName: string;
+} | null>;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};