@appilots/cli 0.11.3 → 0.13.0

package/README.md

@@ -22,14 +22,14 @@ appilots watch                    # re-sync automatically on file changes
 
 ## All commands
 
-| Command | Description |
-|---------|-------------|
+| 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 |
+| `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`)
 
@@ -59,9 +59,9 @@ Created by `appilots init`. Supports these fields:
 
 All commands accept configuration via environment variables, so CI pipelines can run without a `.appilotsrc`:
 
-| Variable | Overrides |
-|----------|-----------|
-| `APPILOTS_API_KEY` | `apiKey` |
+| Variable              | Overrides   |
+| --------------------- | ----------- |
+| `APPILOTS_API_KEY`    | `apiKey`    |
 | `APPILOTS_PROJECT_ID` | `projectId` |
 | `APPILOTS_SERVER_URL` | `serverUrl` |
 
@@ -80,7 +80,19 @@ appilots sync --api-key ak_xxx --server https://api.appilots.com
 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
+5. The Appilots backend combines this document with the current SDK observation to ground agent decisions
+
+### Icon controls without labels
+
+`generate` and `sync` also produce `control-evidence.json` in `outputDir`. This local sidecar preserves icon symbols, handler references, symbolic arguments, mounting conditions, and supported native confirmation evidence for source controls with `onPress`. Screen descriptors include `controlCandidates`; these are evidence, not new executable actions.
+
+The extractor follows direct icon-library imports, including aliases and namespace imports, and inspects JSX in presentation slots and nested render props. It preserves exported glyph names even when the local name does not contain `Icon`. Handler analysis follows local function aliases, React's `useCallback`, class methods, and invoked local helpers within bounded lexical analysis. JSX spread order is respected: if a later opaque spread can replace the callback, the known child glyph can remain as evidence, but uncertain handler calls and arguments are withheld. Literal business arguments and handler bodies are not copied into this evidence.
+
+With a compatible SDK, the existing `withAppilots` Metro integration chains the app's configured Babel transformer and adds source metadata to the compiled JSX. It does not edit client source files. The SDK binds that metadata to a currently mounted control and its list entity before offering an executable identifier. Annotated wrappers may forward the same callback to a single native pressable; a different nested callback or multiple pressables remains ambiguous. Ambiguous, disabled, removed, or unbound controls remain unavailable. An icon name alone never authorizes a destructive operation.
+
+Regenerate after changing source and restart Metro so the new sidecar participates in transformation and caching. Source hashes must match; stale evidence is not inserted. If the CLI uses a custom `outputDir`, pass the same directory to `withAppilots(config, { outputDir: 'your-directory' })`. This bridge requires a configured `babelTransformerPath` and compatible CLI, SDK, and API versions; a CLI-only update cannot enable runtime dispatch.
+
+Static analysis is partial: cross-file barrel/re-export chains, imported/opaque handler bodies, arbitrary hook wrappers, dynamically drawn icons, and unsupported build systems may need additional evidence. Presentation-slot JSX is source evidence, not proof that the slot is currently rendered. The runtime binding remains necessary. This feature does not add screenshot interpretation, discover every off-screen gesture, or prove that an action's effect persisted.
 
 ## Recommended project structure