@edgestore/cli 1.0.0-next.3 → 1.0.0-next.4

package/README.md

@@ -1,6 +1,8 @@
 # EdgeStore CLI
 
-The official command-line interface for EdgeStore accounts and projects.
+Manage EdgeStore accounts, projects, and agent setup from the terminal.
+
+## Install and log in
 
 ```sh
 npm install --global @edgestore/cli
@@ -14,14 +16,133 @@ edgestore login
 edgestore init
 ```
 
+`init --install` selects packages from the application's dependencies. Next.js,
+Remix/React Router, and TanStack Start receive server and React packages. Astro,
+Hono, Express, and Fastify receive the server package, plus the React package
+when React is declared. React-only frontends receive the React package.
+Already-declared EdgeStore packages are left unchanged.
+
 Use `edgestore login --device` when a local browser callback is unavailable.
 Use `edgestore login --token` or `EDGESTORE_TOKEN` for automation. Persisted
 credentials are stored in the operating system credential store and are never
 written to a plaintext config file.
 
-The CLI manages accounts, projects and their keys, management tokens, buckets,
-files, uploads, team members, and invitations. Secrets are returned only when
-they are created:
+## Application context
+
+Inspect installed EdgeStore versions and local reference paths without logging in:
+
+```sh
+edgestore --cwd apps/web agent context --json
+```
+
+At an unlinked workspace root with child packages, it lists them and returns exit
+code 2. Select an application with `--cwd`, or use `--cwd .` to select the root.
+The JSON uses schema
+version 1 and includes installed versions, reference paths, and skill and MCP
+configuration status.
+
+Yarn Plug'n'Play resolution is not supported. When a PnP loader is present,
+declared packages report `unsupported-resolution` and compatibility is
+`unresolved`. Use the project's Yarn environment to inspect installed versions.
+
+## Agent setup and updates
+
+```sh
+edgestore agent setup --client codex --dry-run --json
+edgestore agent setup --client codex --yes
+edgestore agent status --client codex --json
+edgestore agent update --client codex --yes
+```
+
+Use `claude` for Claude Code or `cursor` for Cursor. Setup installs the skill and
+configures MCP for the project. `--skills-only` leaves MCP settings untouched;
+`--global` installs for all projects.
+
+| Client | Skill directory |
+| --- | --- |
+| Codex | `.agents/skills` |
+| Claude Code | `.claude/skills` |
+| Cursor | `.cursor/skills` |
+
+These paths are relative to the Git or package root, or your home for global
+setup. The CLI reports existing global skills without installing a duplicate.
+
+The skill comes from the installed CLI release. `status` compares against that
+copy, not an online release. `setup` leaves older installed copies in place;
+use `update` to replace them. Neither command upgrades application packages.
+
+Keep `.edgestore/skill-assets.json` with the installed skill. Updates stop on
+user edits, extra files, or symlinks, even with `--yes`. If a write fails, the error
+lists files already changed. Restart the client or open a new task after updating.
+
+The repository plugin bundles the same skill and the hosted MCP connection for
+Codex, Claude Code, and Cursor. If you use the plugin, skip `agent setup` and
+`mcp setup` and sign in through your client's MCP controls. The CLI leaves
+skills installed through other tools untouched.
+
+## Direct MCP configuration
+
+Configure the hosted connection independently of skills or plugins:
+
+```sh
+edgestore mcp setup --client codex --dry-run --json
+edgestore mcp setup --client codex --yes
+edgestore mcp status --client codex --json
+edgestore mcp remove --client codex --yes
+```
+
+Use `codex`, `claude` for Claude Code, or `cursor`. Setup writes to the Git root,
+or the package root outside Git. Use `--cwd` to select the project and `--global`
+for user configuration. Automated writes require `--yes`.
+
+| Client | Project configuration | User configuration |
+| --- | --- | --- |
+| Codex | `.codex/config.toml` | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` |
+| Claude Code | `.mcp.json` | `~/.claude.json` |
+| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
+
+Setup preserves existing connections, unrelated settings, and JSONC comments.
+
+Keep `.edgestore/agent-assets.json` with the config. Global setup stores this
+metadata in the CLI's user config directory. Removal requires an unchanged entry
+created by this CLI. `--yes` does not override user edits or name conflicts.
+If a write fails, the error lists files already changed.
+
+Setup uses `https://api.edgestore.dev/mcp`; `--api-url` does not change it.
+`status` checks configuration only. Sign in and grant permissions through your
+client. Codex also requires project trust for project-local configuration.
+
+Client documentation: [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli),
+[Claude Code MCP](https://code.claude.com/docs/en/mcp), and
+[Cursor MCP](https://prod.cursor.com/help/customization/mcp).
+
+## Local diagnostics
+
+```sh
+edgestore --cwd apps/web doctor --offline --json
+edgestore --cwd apps/api doctor --json
+```
+
+`--offline` skips credentials and network access. Normal doctor uses an existing
+credential for read-only API checks. It does not log in or refresh credentials.
+
+Checks return `pass`, `warn`, `fail`, or `skip`. A failure sets exit code 1.
+Doctor checks adapter and provider imports, CORS, and env file locations without
+running application code or returning env values. It cannot verify route mounting,
+provider ancestry, custom env loading, or remote bucket mappings.
+
+The output lists skipped checks and scan limits.
+
+## Project keys and tokens
+
+Interactive commands display a new secret once. Automated key creation, key
+rotation, and token creation require `--output` to a gitignored backend env file.
+JSON returns metadata and delivery status, without `secretKey` or `secret`.
+Scripts that read those fields must switch to file delivery.
+
+Automated `project create` requires `--without-key`. Create its key separately
+with `project key create --output`. Clipboard-only delivery is not supported
+for automated commands.
 
 ```sh
 edgestore project list
@@ -30,6 +151,12 @@ edgestore file upload ./logo.png --bucket publicFiles
 edgestore project key create <basePath> --name local --output .env.local
 ```
 
+`init` reuses its configured env destination, or detects existing env files before
+choosing `.env.local`. For an ambiguous noninteractive destination, pass `--output`
+explicitly after checking which file the backend loads.
+
+## Workspaces
+
 In a monorepo, run commands from the application package or select it
 explicitly with `--cwd`:
 
@@ -44,6 +171,8 @@ it uses the only configured package automatically or asks which package to use
 when more than one is configured. Automation should pass `--cwd` or an explicit
 `--project` when the choice is ambiguous.
 
+## Output
+
 Use `--json` for structured output and `--plain` for commands with one natural
 value. Both modes are non-interactive, so pass required choices explicitly and
 use `--yes` when a command requires confirmation. Run `edgestore completion

package/agent-assets/skills.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "revision": "2375f47ee6205bc5ac25c1f500a543dbfb7470ab9689d7f7051ca262f5d6a6ef",
+  "files": {
+    "edgestore-setup/SKILL.md": "---\nname: edgestore-setup\ndescription: Use when adding, extending, or troubleshooting EdgeStore file uploads, upload UI, or bucket access policies in a TypeScript/React application. Not for unrelated storage migrations or account administration.\nlicense: MIT\n---\n\n# EdgeStore setup\n\nImplement uploads through the application's UI and server route. Verify the upload\nand retrieval there; if runtime access is unavailable, report what remains untested.\n\n## Establish the application and API version\n\nUse `edgestore --cwd <app> agent context --json` when the CLI is available. Otherwise\ninspect the selected workspace's manifests, installed EdgeStore package metadata,\nexisting routes/provider, and backend env-file convention. In a monorepo identify\nthe frontend and backend separately. Use the app's package versions, not the CLI's.\n\nRead the relevant installed `@edgestore/server`, `@edgestore/react`, or\n`@edgestore/sdk` `agent-docs/README.md` and follow its local references. These\nbelong to the installed package version; the skill and CLI can be newer. If the\nreference is absent, use installed types/source and version-matched documentation,\nand mention the fallback. Read the references again after installing packages.\n\nFor an existing 0.2 integration, resolve maintenance versus migration with the\nuser before changing APIs. Preserve installed versions unless an upgrade is\nauthorized. For missing packages choose a compatible, explicit version. Use a\nprerelease only when requested or required by the application.\n\n## Choose the integration\n\nReuse the app's architecture, existing buckets, and configured storage provider.\nRead the matching installed server reference: `next.md` (App or Pages Router),\n`tanstack-start.md`, `remix.md` (Remix or React Router framework mode), `astro.md`,\n`hono.md`, `express.md`, or `fastify.md`. Check the app's routing convention and\nframework version before adapting examples. A React Router client-side app still\nneeds a backend. Reuse the existing backend or ask which one to add. Preserve S3,\nAzure, and custom providers rather than provisioning hosted EdgeStore resources.\n\nInfer a bucket name from the application's feature (for example avatars or\nattachments); fall back to `publicFiles` when context is insufficient. Infer public\nversus protected access from the application and disclose the decision in the\ninitial implementation plan or after implementation. Ask when the access policy\nis ambiguous or the files may be sensitive. Configure the application's\nauthorization rules for protected files.\n\nBefore provisioning, know the selected app/backend, intended provider, account,\nproject, bucket identity, access policy, and env destination. Reuse an existing env\nfile when the backend already loads it; otherwise use the framework's convention.\nPreserve existing env values.\n\n## Use MCP and the CLI\n\nPrefer an available MCP for an action it supports; otherwise use the CLI if\navailable. Start with read-only discovery and request only the permissions needed.\nIf authentication requires the user, explain the sign-in step and continue local work.\n\nCreating resources requires authorization for that setup. A project already\ncreated through MCP should be linked locally, not created again through CLI.\nAfter an uncertain mutation result, inspect for the resource before retrying or\nswitching tools. Do not delete/empty buckets, revoke keys, enable billable overage, or\nchange unrelated resources as an implicit setup step.\n\nFor hosted provisioning or credential delivery, read\n[references/hosted-setup.md](references/hosted-setup.md).\n\n## Implement and verify\n\nConfigure the backend router/provider and the matching client endpoint using\ninstalled references. Keep server keys in a loaded, gitignored backend env file,\nnot frontend variables (`VITE_*`, `NEXT_PUBLIC_*`).\nIn split workspaces, export the real backend router type and import it with\n`import type` on the frontend. For cross-origin calls, configure CORS for the\nintended frontend origin. Wrap the upload UI with the React provider.\n\nFor a failing integration, read the installed server's `troubleshooting.md` and\nthe React package's `errors.md`. Diagnose the failing app request before changing\nremote resources or credentials.\n\nRun `edgestore --cwd <app> doctor --offline` when available, plus the app's own\ntypecheck/build/tests. Investigate doctor warnings and skipped checks. Start the\napp, upload a small test file through its UI and server route, and independently\nretrieve and check the bytes.\nFor protected access, verify unauthenticated retrieval is denied and authorized\nretrieval works.\n\nUse the account and project authorized for testing. Keep credentials and signed\nURLs out of agent output; retrieve protected files in a local process that returns\nonly the result. Clean up only this task's test resources. Summarize the integration\nchoices, checks performed, blockers, and any test resources left behind.\n",
+    "edgestore-setup/agents/openai.yaml": "interface:\n  display_name: \"EdgeStore Setup\"\n  short_description: \"Use when adding or troubleshooting EdgeStore file uploads.\"\n",
+    "edgestore-setup/references/hosted-setup.md": "# Hosted setup and credential handoff\n\nUse MCP first for supported account/project/bucket discovery and authorized\nchanges; otherwise use the CLI. Confirm the account and project in the tool's\nmetadata before making changes.\n\nTo configure MCP:\n\n```sh\nedgestore mcp setup --client codex --dry-run --json\nedgestore mcp setup --client codex --yes\n```\n\nUse `claude` or `cursor` for those clients. Setup configures\n`https://api.edgestore.dev/mcp`. Sign in through your client and review the\nrequested permissions.\n\nCheck `--help` for the installed CLI's available commands. Use `--json` and file\ndelivery to keep secrets out of tool output. Let the user complete any required login.\n\nAfter MCP creates/selects a project, link the backend to that same project and\nexisting env convention:\n\n```sh\nedgestore --cwd <backend> project link <project-base-path> --env-file <env-file> --json\n```\n\nReuse an existing valid backend key when possible. When a new key is authorized:\n\n```sh\nedgestore --cwd <backend> project key create <project-base-path> --name local --output <env-file> --json\n```\n\nThe destination must be gitignored. If values already exist, inspect the\nconfiguration before considering `--update`. Check key presence and project\nassociation without reading secret values into agent context. If file delivery is\nunavailable, ask the user to configure the key locally, not paste it into chat.\nOn partial failure, follow the returned recovery status before retrying.\n\n`init` provisions or links resources. Use `project link` when MCP has already\ncreated the project.\n"
+  }
+}