@elixpo/lixblogs-cli 1.1.2 → 1.3.3

package/API.md

@@ -20,6 +20,7 @@ logged by the resource API.
 | Method | Path | Scope | Behavior |
 | --- | --- | --- | --- |
 | `GET` | `/api/v1` | public | API and compatibility metadata |
+| `GET` | `/api/v1/me` | `lixblogs:profile:read` | Current LixBlogs identity |
 | `GET` | `/api/v1/blogs` | `lixblogs:blog:read` | Accessible blog metadata |
 | `GET` | `/api/v1/blogs/{id}` | `lixblogs:blog:read` | One accessible blog and its content |
 | `POST` | `/api/v1/blogs` | `lixblogs:blog:write` | Create a draft |
@@ -28,6 +29,23 @@ logged by the resource API.
 | `POST` | `/api/v1/blogs/{id}/unpublish` | `lixblogs:blog:publish` | Return a post to draft |
 | `DELETE` | `/api/v1/blogs/{id}` | `lixblogs:blog:delete` | Move a post to trash |
 | `POST` | `/api/v1/blogs/{id}/restore` | `lixblogs:blog:delete` | Restore a trashed post |
+| `GET` | `/api/v1/orgs` | `lixblogs:organizations:read` | Organizations the caller belongs to |
+| `GET` | `/api/v1/orgs/{id}` | `lixblogs:organizations:read` | One caller-visible organization and role |
+| `GET` | `/api/v1/orgs/{id}/collections` | `lixblogs:organizations:read` | Collections within a caller membership |
+| `GET` | `/api/v1/orgs/{id}/members` | `lixblogs:organizations:read` | Members and roles within a caller membership |
+| `GET` | `/api/v1/blogs/{id}/collaborators` | `lixblogs:collaboration:read` | Editorial team and effective role |
+| `POST` | `/api/v1/blogs/{id}/collaborators` | `lixblogs:collaboration:write` | Invite or reassign a collaborator |
+| `PATCH` | `/api/v1/blogs/{id}/collaborators` | `lixblogs:collaboration:write` | Change a collaborator role |
+| `DELETE` | `/api/v1/blogs/{id}/collaborators` | `lixblogs:collaboration:write` | Remove a collaborator or leave a team |
+| `GET` | `/api/v1/collaboration/invitations` | `lixblogs:collaboration:read` | Current identity's invitations |
+| `POST` | `/api/v1/collaboration/invitations` | `lixblogs:collaboration:write` | Accept or decline an invitation |
+| `GET` | `/api/v1/analytics` | `lixblogs:analytics:read` | Bounded creator analytics dimensions |
+
+`GET /api/v1/analytics` accepts `scope=personal|org:<id>`, `range=7d|30d|90d|12m|custom`,
+`from`, `to`, `dimension=overview|timeline|posts|sources|devices|countries`, `limit=1..100`,
+and an opaque `cursor`. Organization queries additionally require `lixblogs:organizations:read`
+and an owner, admin, or maintain membership. Responses contain aggregate creator data;
+visitor identifiers are never returned.
 
 `GET /api/v1/blogs` accepts `status=all|draft|published`, `limit=1..100`, and
 an opaque `cursor`. Results include authored blogs, accepted collaborations,

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+Release notes are generated from merged pull requests. This file records contract-level changes that users must see before upgrading.
+
+## 1.3.0
+
+- Added scoped organization and editorial commands.
+- Added bounded, read-only creator analytics with JSON and CSV export.
+- Bundled five independently installable LixBlogs agent skills.
+- Added packed-artifact, Accounts device-flow, Blogs resource-contract, provenance, and rollback release gates.

package/README.md

@@ -3,9 +3,9 @@
 The official CLI for LixBlogs — publish, manage, and inspect blogs through
 the supported API. Built for creators and agent/automation use.
 
-**Status: initial release.** This package implements production device-flow
-authentication and the core blog lifecycle over the stable LixBlogs API v1
-contract. The interactive terminal UI is intentionally a separate follow-up.
+This package implements production device-flow authentication and the core
+blog lifecycle over the stable LixBlogs API v1 contract. Its output stays
+compact and predictable for both terminals and automation.
 
 ## Install (local development)
 
@@ -14,7 +14,6 @@ cd packages/lixblogs-cli
 npm install
 ```
 
-There's no published npm release yet. Once available, install will be:
 ```bash
 npm install -g @elixpo/lixblogs-cli
 ```
@@ -29,22 +28,35 @@ node bin/lixblogs.mjs --help
 
 ```bash
 # Log in via device authorization
-node bin/lixblogs.mjs auth login
+node bin/lixblogs.mjs login
+# Credentials are saved under the authenticated username and made active.
+
+# Save credentials under an explicit local profile name
+node bin/lixblogs.mjs login --profile personal
 
 # Check login status
-node bin/lixblogs.mjs auth status
+node bin/lixblogs.mjs whoami
 
 # List profiles and choose the active one
-node bin/lixblogs.mjs auth profiles
-node bin/lixblogs.mjs auth use work
+node bin/lixblogs.mjs profiles
+node bin/lixblogs.mjs use work
 
 # Log out (clears local credentials only)
-node bin/lixblogs.mjs auth logout
+node bin/lixblogs.mjs logout
 
 # Revoke the token server-side and clear local credentials (destructive)
 node bin/lixblogs.mjs auth revoke --yes
 ```
 
+Interactive login shows one compact device card and stays quiet while Accounts
+approval is pending. Press Enter to open the verification URL locally, use
+`--open` to open it immediately, or copy the URL to any browser when connected
+to a VPS. Device authorization does not require a localhost callback or an
+exposed port. The authenticated username becomes the local profile alias unless
+`--profile` explicitly overrides it. Run `lixblogs login` again to add another
+account, `lixblogs profiles` to list saved accounts, and
+`lixblogs use <username>` to switch the active one.
+
 ### Blog lifecycle
 
 Request the permissions needed for the operations you intend to use:
@@ -63,13 +75,72 @@ lixblogs blog list --status draft
 lixblogs blog create --file post.md --title "A new post" --tag engineering
 lixblogs blog get <id> --json
 lixblogs blog edit <id> --editor
-lixblogs blog publish <id>
-lixblogs blog unpublish <id>
+lixblogs blog publish <id> --yes
+lixblogs blog unpublish <id> --yes
 lixblogs blog delete <id> --yes
 lixblogs blog list --status trashed
-lixblogs blog restore <id>
+lixblogs blog restore <id> --yes
+```
+
+Inspect valid publication targets before assigning organization metadata:
+
+```bash
+lixblogs org list
+lixblogs org get ORG_ID
+lixblogs org collections ORG_ID
+lixblogs org members ORG_ID
+lixblogs org targets --json
+```
+
+Organization lookup is membership-bound. A slug alone never grants access;
+the API resolves the authenticated user's role before returning tenant data.
+
+Editorial collaboration stays separate from publishing:
+
+```bash
+lixblogs collab invitations
+lixblogs collab list BLOG_ID
+lixblogs collab invite BLOG_ID --user reviewer --role viewer --yes
+lixblogs collab role BLOG_ID --user reviewer --role editor --yes
+lixblogs collab accept BLOG_ID --yes
+lixblogs collab decline BLOG_ID --yes
+```
+
+Viewer, editor, and admin roles grant different editorial authority. None of
+these commands publishes a post; public-state changes still use `blog publish`
+with the publish scope and a separate confirmation.
+
+### Creator analytics
+
+Analytics is read-only and uses bounded date ranges and dimensions:
+
+```bash
+lixblogs login --scope openid --scope profile --scope lixblogs:analytics:read
+lixblogs analytics query --range 30d --dimension overview --json --no-input
+lixblogs analytics query --scope org:ORG_ID --range custom \
+  --from 2026-07-01 --to 2026-07-31 --dimension posts --limit 25 --json --no-input
+lixblogs analytics export --dimension timeline --format csv --output analytics.csv
+```
+
+Organization analytics also requires `lixblogs:organizations:read`. Results contain
+aggregates only; the API does not expose visitor identifiers or credentials.
+Exports refuse to overwrite an existing file.
+
+### Agent skills
+
+The npm artifact bundles each skill independently:
+
+```bash
+lixblogs skill list
+lixblogs skill inspect lixblogs-author
+lixblogs skill install lixblogs-author --target .agents/skills --dry-run
+lixblogs skill install lixblogs-author --target .agents/skills --yes
 ```
 
+Install only the skill needed by the current agent. Existing files are not
+replaced unless `--force --yes` is explicit. The bundled skill declares its
+minimum compatible CLI version and scopes.
+
 `create`, `edit`, `publish`, `unpublish`, `delete`, and `restore` accept
 `--dry-run`. Content input is mutually exclusive: `--file`, `--stdin`,
 `--content`, or `--editor`. Permanent deletion additionally requires
@@ -80,7 +151,7 @@ command exits with code 3 and retains both versions under
 `.lixblogs-conflicts/`; it never overwrites the newer server revision.
 
 Global flags:
-- `--profile <name>` — named profile to use (default: `"default"`)
+- `--profile <name>` — override the username-based local account alias
 - `--env <environment>` — override environment (`development` | `staging` | `production`)
 - `--scope <scope>` — request an additional/alternate OAuth scope; repeatable
 - `--open` — open the verification URL with the device code pre-filled
@@ -89,7 +160,7 @@ Global flags:
   `https://blogs.elixpo.com`
 - `--json` — machine-readable JSON output
 - `--quiet` — suppress non-essential output
-- `--yes`, `-y` — auto-confirm destructive actions (required for `revoke`)
+- `--yes`, `-y` — confirm publishing and destructive state changes
 - `--allow-insecure-fallback` — explicit opt-in: if the OS keychain is
   unavailable, use a non-persistent in-memory store instead of failing
 
@@ -103,10 +174,34 @@ Global flags:
   environment, for example `--env development --auth-provider mock`.
 - The resource contract, scopes, pagination, errors, and mutation guarantees
   are documented in [API.md](API.md).
+- Release compatibility, provenance, smoke gates, and rollback are documented
+  in [RELEASE.md](RELEASE.md). Contract changes are summarized in
+  [CHANGELOG.md](CHANGELOG.md).
 
 The production client is public and has no client secret. Never add one to
 CLI configuration, package files, or GitHub secrets.
 
+### Configuration precedence
+
+Configuration resolves in this order: command flags, `LIXBLOGS_*` environment
+variables, the selected named profile, then production-safe defaults. Use
+`lixblogs whoami --json --no-input` to verify the active profile, environment,
+granted scopes, and expiry before automation. Flags are best for one command;
+environment values are best for a contained CI job. Credentials remain in the
+OS keychain and are never read from environment variables.
+
+### Troubleshooting
+
+- `invalid_scope`: Accounts has not registered the requested permission for
+  this client; do not substitute a broader token.
+- `insufficient_scope`: log in again with only the reported missing scope.
+- `account_not_provisioned`: sign in to LixBlogs once with the same Accounts
+  identity before retrying the CLI.
+- `precondition_failed`: fetch the current post, reconcile the retained
+  conflict copy, and retry with the new revision.
+- `rate_limit_exceeded`: honor `Retry-After`; do not fan out retries.
+- Include the returned request ID in a report, never a token or credential.
+
 ## Development
 
 ```bash
@@ -146,10 +241,8 @@ tests.
 See [#135](https://github.com/elixpo/blogs.elixpo/issues/135) for the full
 scope. Rough remaining order:
 
-1. Media, organization, and stats commands
-2. Packaging and release automation
-3. Interactive terminal UI and branding in a separate issue
-4. Agent skill packages and cross-repository E2E coverage
+1. Media commands
+2. Interactive terminal UI and branding in a separate issue
 
 ## Contributing
 

package/RELEASE.md

@@ -0,0 +1,30 @@
+# Release and compatibility policy
+
+## Compatibility
+
+- CLI `1.x` targets LixBlogs API `/api/v1` and the Accounts OAuth discovery contract.
+- Additive response fields and commands are minor releases. Fixes without contract changes are patch releases.
+- Removing a command, field, scope, or error code requires a CLI major release or API `/api/v2`.
+- The resource metadata `minCliVersion` is authoritative. An older client must stop before authenticated requests and ask the user to upgrade.
+- Node 18 is the supported runtime floor. Release gates run on Node 22.
+
+## Release
+
+1. Update the package version and `CHANGELOG.md` in a reviewed PR.
+2. Run the manual **LixBlogs CLI release gate**. It tests the package, installs the exact tarball, checks bundled skills, verifies Blogs resource contracts, and runs the Accounts device-flow contract.
+3. Tag the reviewed commit as `lixblogs-cli-vX.Y.Z`.
+4. The publish workflow reruns the gate, checks that tag and package versions match, attests the tarball, publishes it through npm trusted publishing with provenance, and creates generated GitHub release notes.
+
+No npm token is stored in this workflow. The npm package must configure this repository and `publish-lixblogs-cli.yml` as a trusted publisher.
+
+## Smoke criteria
+
+The packed artifact must install into an empty prefix, render `--help`, discover all five scoped skills, and pass auth, blog lifecycle, organization, collaboration, and analytics command tests. Accounts must pass device approval, refresh rotation, replay protection, and revocation. Blogs must pass bearer validation, concurrency/idempotency, analytics, and media request-boundary tests.
+
+## Rollback
+
+1. Stop a broken release with `npm deprecate @elixpo/lixblogs-cli@X.Y.Z "Do not use; upgrade to X.Y.N"`.
+2. Restore the previous compatible version with `npm dist-tag add @elixpo/lixblogs-cli@GOOD latest`.
+3. Open a patch PR; never reuse or delete the published version.
+4. Re-run the release gate and publish a new patch tag.
+5. If the API contract caused the failure, raise `minCliVersion` only after the compatible patch is available.