@botlr/cli 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @botlr/cli
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @botlr/sdk@0.2.0
+
+## 0.1.0
+
+- First release: `botlr pull`, `botlr push`, `botlr sections list`,
+  `botlr sections status` and `botlr sections init`, against the section
+  source bridge contract.
+- Config from `botlr.config.json`, `BOTLR_*` environment variables and
+  flags; pull state in `.botlr/sections.lock.json`.

package/LICENSE

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

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @botlr/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `botlr` command pulls section source from a Botlr site into an app's
+codebase and pushes it back as a new version. It is the client side of the
+section source bridge; `@botlr/sdk` does the HTTP.
+
+```bash
+pnpm add -D @botlr/cli
+```
+
+## Configuration
+
+`botlr.config.json` in the app root (the CLI searches upward from the cwd):
+
+```json
+{
+  "baseUrl": "https://api.botlr.io",
+  "appId": "00000000-0000-0000-0000-000000000000",
+  "framework": "react-next",
+  "sectionsDir": "components/sections"
+}
+```
+
+Environment: `BOTLR_API_KEY` (site token, for pull/list/status) and
+`BOTLR_PAT` (personal access token with `write:sections`, for push).
+`BOTLR_BASE_URL`, `BOTLR_APP_ID`, `BOTLR_FRAMEWORK` and `BOTLR_SECTIONS_DIR`
+override the file; `--framework` and `--dir` override both.
+
+## Commands
+
+```
+botlr pull <name...> | --all  [--framework react-next] [--dir components/sections] [--version N] [--shared] [--force]
+botlr push <name>             [-m msg] [--shared] [--create] [--force]
+botlr sections list
+botlr sections status [name...] [--offline]
+botlr sections init           [--force] [--dry-run]
+```
+
+- `pull` writes every file of the section under `sectionsDir`, plus
+  `<name>.botlr.json` (the manifest, never holding version or hash) and the
+  lock entry in `.botlr/sections.lock.json`. A section whose local files
+  changed since the last pull is skipped unless `--force`.
+- `push` reads the manifest and its files, hashes them, and pushes with
+  `baseVersion` from the lock so a stale checkout gets a conflict instead of
+  overwriting someone's version. `--force` omits `baseVersion`. `--create`
+  adds the section definition when the dashboard does not know it yet.
+- `sections status` compares the local content hash with the lock and the
+  server's latest: `clean`, `modified`, `behind`, `diverged`, or
+  `untracked` for a manifest with no lock entry.
+- `sections init` derives first manifests from a satellite app's
+  `publisher-section-registry.ts` and the `XDefinition` exports next to each
+  component. Review them, then `botlr push <name> --create` per section.
+
+Commit the manifests and the lock file; keep `BOTLR_PAT` out of the repo.