@appilots/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appilots Team
+
+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,96 @@
+# appilots
+
+CLI that analyzes your React Native project and syncs its structure (screens, navigation, forms, actions) with the Appilots platform — enabling AI agents to understand and operate your app.
+
+## Installation
+
+```bash
+# Global (recommended)
+npm install -g @appilots/cli
+
+# Or run directly with npx
+npx appilots init --api-key ak_xxx
+```
+
+## Quick start
+
+```bash
+appilots init --api-key ak_xxx   # configure project (saves .appilotsrc)
+appilots sync                     # analyze code + upload to Appilots
+appilots watch                    # re-sync automatically on file changes
+```
+
+## All commands
+
+| Command | Description |
+|---------|-------------|
+| `appilots init --api-key <key>` | Configure project, validate credentials, create `.appilotsrc` |
+| `appilots sync` | Analyze source, generate context document, upload to Appilots |
+| `appilots sync --force` | Force upload even if nothing changed |
+| `appilots watch` | Watch for file changes and auto-sync |
+| `appilots generate` | Generate context document locally (no upload) |
+| `appilots status` | Show local config and remote project status |
+
+## Configuration (`.appilotsrc`)
+
+Created by `appilots init`. Supports these fields:
+
+```json
+{
+  "apiKey": "ak_xxx",
+  "projectId": "proj_xxx",
+  "serverUrl": "http://localhost:4000",
+  "outputDir": ".appilots",
+  "autoActivate": true,
+  "strictScreens": false,
+  "screenPatterns": ["**/*Screen.{ts,tsx}", "**/screens/**/*.{ts,tsx}"],
+  "include": ["src/**/*.{ts,tsx}"],
+  "exclude": ["**/__tests__/**"],
+  "navigationInclude": ["**/routing/**/*.{ts,tsx}"],
+  "navigationExclude": []
+}
+```
+
+**`strictScreens`** — defaults to `true`. Only files that call `registerScreen()` or match `screenPatterns` are included as screens. This keeps components, hooks, config files, and utilities out of the agent's screen map.
+
+> **⚠️ `.appilotsrc` contains your API key — never commit it.** `appilots init` adds it to your `.gitignore` automatically when one exists; double-check if you manage ignores elsewhere.
+
+## Environment variables (CI/CD)
+
+All commands accept configuration via environment variables, so CI pipelines can run without a `.appilotsrc`:
+
+| Variable | Overrides |
+|----------|-----------|
+| `APPILOTS_API_KEY` | `apiKey` |
+| `APPILOTS_PROJECT_ID` | `projectId` |
+| `APPILOTS_SERVER_URL` | `serverUrl` |
+
+Precedence: command-line flags > environment variables > `.appilotsrc`.
+
+```bash
+# CI example — no .appilotsrc needed
+APPILOTS_API_KEY=ak_xxx appilots sync
+# or with flags
+appilots sync --api-key ak_xxx --server https://api.appilots.com
+```
+
+## How it works
+
+1. Babel AST analysis extracts screens, navigation graph, forms, and actions from your React Native source
+2. `registerScreen()` calls (from `@appilots/sdk`) are the primary metadata source; JSX analysis enriches anything not declared
+3. A context document (JSON) is generated with a SHA-256 checksum
+4. On `sync`, the document is uploaded to Appilots only if the checksum changed (skip with `--force`)
+5. The Appilots backend uses this document to give AI agents full awareness of your app structure
+
+## Recommended project structure
+
+The CLI works best with these conventions (but is configurable via `.appilotsrc`):
+
+- Screens in `src/screens/` or files named `*Screen.tsx`
+- Navigation in `src/navigation/` or files named `navigator*` / `routes*`
+- Each screen calls `registerScreen()` from `@appilots/sdk` with metadata
+
+## Links
+
+- [Appilots SDK docs](https://docs.appilots.com)
+- [Getting started guide](https://docs.appilots.com/getting-started)