feat: add yavy project create command

Author: vildanbina

.gitignore

@@ -4,3 +4,4 @@ dist
 .omc
 *.log
 *.tgz
+.claude

CLAUDE.md

@@ -0,0 +1,49 @@
+# @yavydev/cli
+
+CLI for searching, managing, and configuring AI-ready documentation on Yavy.
+
+## Commands
+
+```bash
+pnpm install              # Install dependencies
+pnpm run build            # Build with tsup
+pnpm run dev              # Build in watch mode
+pnpm test                 # Run tests (vitest)
+pnpm run typecheck        # Type check without emitting
+pnpm run format:check     # Check formatting (prettier)
+pnpm run format           # Fix formatting
+```
+
+## Architecture
+
+The CLI is built on Commander.js with a modular command structure. Each command is a factory function returning a `Command` instance, registered in the entry point.
+
+- **Commands** - one directory or file per command group. Each exports a factory.
+- **API Client** - token-based HTTP client with retry logic and exponential backoff.
+- **Auth** - OAuth2 PKCE flow with local callback server; credentials stored in `~/.yavy/`.
+- **Prompts** - interactive flows using @clack/prompts for multi-select and @inquirer/prompts for input/select.
+
+See [docs/architecture.md](docs/architecture.md) for details.
+
+## Key Design Decisions
+
+- `@/` path aliases throughout (configured in tsconfig, tsup, vitest).
+- Commands set `process.exitCode` instead of calling `process.exit()` directly - keeps code testable.
+- Two auth patterns coexist: OAuth (login flow) and token-based (API token via env or config file).
+- Interactive mode activates when required CLI flags are missing; flags always take precedence.
+
+## After Changing Commands
+
+- Register new commands in the entry point.
+- Add the command to README.md under the Commands section.
+- If adding a new command group, create a directory under `src/commands/`.
+
+## After Changing the API Client
+
+- Update tests that mock fetch globally.
+- If adding new response types, define them alongside existing API interfaces in the client module.
+
+## Documentation
+
+- [Architecture](docs/architecture.md) - layers, data flow, design decisions
+- [README](README.md) - install, quick start, command reference

README.md

@@ -63,6 +63,22 @@ Lists all projects you have access to across your organizations.
 | -------- | -------------- |
 | `--json` | Output as JSON |
 
+### `yavy project create`
+
+Create a new documentation project. Runs interactively when `--url` or `--github` is omitted.
+
+| Flag              | Description                              |
+| ----------------- | ---------------------------------------- |
+| `--url <url>`     | Documentation URL (web crawl source)     |
+| `--github <repo>` | GitHub repository (e.g. laravel/docs)    |
+| `--org <slug>`    | Organization slug                        |
+| `--name <name>`   | Project name (auto-generated if omitted) |
+| `--public`        | Make project public (default)            |
+| `--private`       | Make project private                     |
+| `--branch <name>` | GitHub branch override                   |
+| `--docs-path <p>` | GitHub docs path                         |
+| `--no-sync`       | Skip initial auto-sync                   |
+
 ### `yavy generate <org/project>`
 
 Downloads a skill from a project's indexed documentation.

docs/architecture.md

@@ -0,0 +1,61 @@
+# Architecture
+
+How the CLI is structured, where things live, and why.
+
+## Layers
+
+### Entry Point
+
+`bin/yavy.js` is the shebang entry that loads the built output. The source entry registers all commands with Commander.js and calls `parseAsync()`. Top-level error handler catches unhandled rejections and exits with code 1.
+
+### Commands
+
+Each command is a factory function that returns a configured `Command`. Commands live in `src/commands/` - either as single files (login, logout, search) or directories when they have submodules (init, project).
+
+Command factories wire up flags, descriptions, and an async action handler. The action handler orchestrates: validate inputs, call API, format output. No business logic lives in the action - it delegates to dedicated modules.
+
+### API Client
+
+Single HTTP client class handles all Yavy API communication. Key behaviors:
+
+- Bearer token auth (loaded from credential store or environment)
+- Retry with exponential backoff on 429/502/503/504
+- Request timeout with AbortController
+- Typed response parsing
+
+### Authentication
+
+Two paths:
+
+1. **OAuth PKCE** - `yavy login` opens browser, spawns local HTTP server for callback, exchanges code for token. Credentials persisted to `~/.yavy/credentials.json` with 0600 permissions. Auto-refresh when token nears expiry.
+2. **Token-based** - `YAVY_API_TOKEN` env variable or `~/.yavy/config.json`. Used by the project creation flow and CI environments.
+
+### Interactive Prompts
+
+When required CLI flags are missing, commands fall back to interactive mode. Prompts collect the missing values, then merge with any flags that were provided. Two prompt libraries are in use: @clack/prompts (multi-select, spinners) and @inquirer/prompts (input, select).
+
+### Utilities
+
+- **Output** - colored terminal helpers (success, error, warn, info) using chalk
+- **Paths** - skill output directories, zip-slip prevention, safe directory creation
+- **Errors** - API error formatting that maps HTTP status codes to actionable messages
+
+## Data Flow
+
+```
+User runs command
+  -> Commander parses flags
+  -> Command action handler runs
+  -> If missing flags: interactive prompts fill them in
+  -> API client makes request (with retry)
+  -> Response formatted and printed to stdout
+  -> Errors caught, formatted, printed to stderr
+```
+
+## Build & Distribution
+
+tsup bundles to ESM targeting Node 20+. The dist includes declarations and source maps. Published to npm as `@yavydev/cli` with `dist/` and `bin/` in the package.
+
+## Testing Strategy
+
+Vitest with globals enabled. Tests mock at module boundaries - the API client, prompts, and filesystem are mocked; pure functions (payload builders, error formatters, org extractors) are tested directly. Console output is verified via spies on console.log/console.error.

src/api/client.ts

@@ -1,6 +1,22 @@
 import { getAccessToken } from '@/auth/store';
 import { MAX_RETRIES, REQUEST_TIMEOUT_MS, YAVY_BASE_URL, YAVY_USER_AGENT } from '@/config';
 
+export class ApiError extends Error {
+    constructor(
+        public readonly status: number,
+        public readonly body: unknown,
+        message?: string,
+    ) {
+        super(message ?? `API request failed with status ${status}`);
+        this.name = 'ApiError';
+    }
+}
+
+export interface OrganizationInfo {
+    name: string;
+    slug: string;
+}
+
 export interface ProjectContext {
     product: string | null;
     type: string | null;
@@ -21,16 +37,19 @@ export interface ApiProject {
     name: string;
     slug: string;
     description: string | null;
-    organization: {
-        name: string;
-        slug: string;
-    };
+    organization: OrganizationInfo;
     pages_count: number;
     last_indexed_at: string | null;
     has_indexed_content: boolean;
+    mcp_url: string;
     context: ProjectContext;
 }
 
+export interface ApiValidationError {
+    message: string;
+    errors: Record<string, string[]>;
+}
+
 export interface SearchResult {
     title: string;
     url: string;
@@ -112,12 +131,14 @@ export class YavyApiClient {
     }
 
     private async handleErrorResponse(response: Response): Promise<never> {
+        const body = await response.json().catch(() => ({}));
+
         if (response.status === 401) {
-            throw new Error('Authentication expired. Run `yavy login` to re-authenticate.');
+            throw new ApiError(401, body, 'Authentication expired. Run `yavy login` to re-authenticate.');
         }
 
-        const errorData = (await response.json().catch(() => ({}))) as { error?: string };
-        throw new Error(errorData.error ?? `API request failed with status ${response.status}`);
+        const errorData = body as { error?: string };
+        throw new ApiError(response.status, body, errorData.error ?? `API request failed with status ${response.status}`);
     }
 
     private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
@@ -146,6 +167,10 @@ export class YavyApiClient {
         return result.data;
     }
 
+    async createProject(orgSlug: string, payload: unknown): Promise<{ data: ApiProject }> {
+        return this.request<{ data: ApiProject }>('POST', `/${encodeURIComponent(orgSlug)}/projects`, payload);
+    }
+
     async search(query: string, options?: { project?: string; limit?: number }): Promise<SearchResponse> {
         const params = new URLSearchParams({ query });
         if (options?.project) params.set('project', options.project);

src/commands/project/build-request.ts

@@ -0,0 +1,39 @@
+import type { CreateProjectOptions, CreateProjectPayload } from '@/commands/project/types';
+
+export function buildCreateProjectPayload(options: CreateProjectOptions): CreateProjectPayload {
+    if (options.url) {
+        return buildWebCrawlPayload(options);
+    }
+
+    if (options.github) {
+        return buildGitHubPayload(options);
+    }
+
+    throw new Error('Either --url or --github is required.');
+}
+
+function buildWebCrawlPayload(options: CreateProjectOptions): CreateProjectPayload {
+    return {
+        url_discovery_mode: 'web_crawl',
+        base_url: options.url,
+        ...sharedFields(options),
+    };
+}
+
+function buildGitHubPayload(options: CreateProjectOptions): CreateProjectPayload {
+    return {
+        url_discovery_mode: 'github_repository',
+        github_repo: options.github,
+        ...(options.branch && { github_branch: options.branch }),
+        ...(options.docsPath && { github_docs_path: options.docsPath }),
+        ...sharedFields(options),
+    };
+}
+
+function sharedFields(options: CreateProjectOptions): Pick<CreateProjectPayload, 'name' | 'is_public' | 'no_sync'> {
+    return {
+        ...(options.name && { name: options.name }),
+        is_public: !options.private,
+        ...(options.noSync && { no_sync: true }),
+    };
+}

src/commands/project/create.ts

@@ -0,0 +1,64 @@
+import { Command } from 'commander';
+import { YavyApiClient } from '@/api/client';
+import { needsInteractiveMode, runInteractiveFlow } from '@/prompts/project-create';
+import { error, formatProjectCreated } from '@/utils';
+import { buildCreateProjectPayload } from '@/commands/project/build-request';
+import { resolveOrg } from '@/commands/project/resolve-org';
+import type { CreateProjectOptions } from '@/commands/project/types';
+
+export function createProjectCommand(): Command {
+    return new Command('create')
+        .description('Create a new documentation project')
+        .option('--url <url>', 'Documentation URL (WebCrawl source)')
+        .option('--github <owner/repo>', 'GitHub repository (e.g. laravel/docs)')
+        .option('--org <slug>', 'Organization slug')
+        .option('--name <name>', 'Project name (auto-generated if omitted)')
+        .option('--public', 'Make project public (default)')
+        .option('--private', 'Make project private')
+        .option('--branch <branch>', 'GitHub branch override')
+        .option('--docs-path <path>', 'GitHub docs path')
+        .option('--no-sync', 'Skip initial auto-sync')
+        .action(async (options: CreateProjectOptions) => {
+            try {
+                await executeCreateProject(options);
+            } catch (err) {
+                if (err instanceof Error && err.message === 'cancelled') {
+                    console.log('\nProject creation cancelled.');
+                    return;
+                }
+                error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+        });
+}
+
+export async function executeCreateProject(options: CreateProjectOptions): Promise<void> {
+    const client = await YavyApiClient.create();
+
+    let resolvedOptions = options;
+
+    if (needsInteractiveMode(options)) {
+        resolvedOptions = await runInteractiveFlow(client, options);
+    }
+
+    if (!resolvedOptions.url && !resolvedOptions.github) {
+        throw new Error('Either --url or --github is required.');
+    }
+
+    if (resolvedOptions.url && resolvedOptions.github) {
+        throw new Error('Provide either --url or --github, not both.');
+    }
+
+    const projects = await client.listProjects();
+    const { slug: orgSlug, orgs } = await resolveOrg(projects, resolvedOptions.org);
+
+    if (!orgSlug) {
+        const slugList = orgs.map((o) => `  - ${o.slug} (${o.name})`).join('\n');
+        throw new Error(`Multiple organizations found. Please specify one with --org <slug>:\n${slugList}`);
+    }
+
+    const payload = buildCreateProjectPayload(resolvedOptions);
+    const response = await client.createProject(orgSlug, payload);
+
+    console.log(formatProjectCreated(response.data));
+}

src/commands/project/resolve-org.ts

@@ -0,0 +1,36 @@
+import type { ApiProject, OrganizationInfo } from '@/api/client';
+
+export function extractUniqueOrgs(projects: Array<{ organization: OrganizationInfo }>): OrganizationInfo[] {
+    const seen = new Set<string>();
+    const orgs: OrganizationInfo[] = [];
+
+    for (const project of projects) {
+        if (!seen.has(project.organization.slug)) {
+            seen.add(project.organization.slug);
+            orgs.push(project.organization);
+        }
+    }
+
+    return orgs;
+}
+
+export async function resolveOrg(
+    projects: ApiProject[],
+    orgFlag: string | undefined,
+): Promise<{ slug: string; orgs: OrganizationInfo[] }> {
+    if (orgFlag) {
+        return { slug: orgFlag, orgs: [] };
+    }
+
+    const orgs = extractUniqueOrgs(projects);
+
+    if (orgs.length === 0) {
+        throw new Error('No organizations found. Please specify an organization with --org <slug>.');
+    }
+
+    if (orgs.length === 1) {
+        return { slug: orgs[0].slug, orgs };
+    }
+
+    return { slug: '', orgs };
+}

src/commands/project/types.ts

@@ -0,0 +1,22 @@
+export interface CreateProjectOptions {
+    url?: string;
+    github?: string;
+    org?: string;
+    name?: string;
+    public?: boolean;
+    private?: boolean;
+    branch?: string;
+    docsPath?: string;
+    noSync?: boolean;
+}
+
+export interface CreateProjectPayload {
+    url_discovery_mode: 'web_crawl' | 'github_repository';
+    base_url?: string;
+    github_repo?: string;
+    github_branch?: string;
+    github_docs_path?: string;
+    name?: string;
+    is_public?: boolean;
+    no_sync?: boolean;
+}