@elixpo/lixblogs-cli 1.1.2 → 1.3.3

package/skills/lixblogs-author/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: lixblogs-author
+description: Draft, inspect, and revise LixBlogs posts through the supported CLI. Use when an agent needs to outline a post, create a draft, update Markdown or metadata, or resolve an edit conflict without publishing or deleting content.
+---
+
+# LixBlogs author
+
+Use `@elixpo/lixblogs-cli` 1.2.0 or newer. Run every automation command with `--json --no-input`. Never use D1, session cookies, passwords, bearer tokens, or direct API calls.
+
+## Access
+
+- Inspect: `lixblogs:profile:read`, `lixblogs:blog:read`
+- Draft or revise: add `lixblogs:blog:write`
+- Do not request publish, delete, organization-write, or collaboration-write scopes for this workflow.
+
+Check the active identity before writing:
+
+```bash
+lixblogs whoami --json --no-input
+```
+
+If a scope is missing, stop and tell the user which scope is required. Do not initiate login without their involvement.
+
+## Workflow
+
+1. Inspect existing work with `lixblogs blog list --status draft --json --no-input` or `lixblogs blog get BLOG_ID --json --no-input`.
+2. Preserve the creator's claims, citations, tone, headings, and code. Mark unsupported facts for review; do not invent them.
+3. Prefer a Markdown file for substantial content. Use stdin for a generated pipeline and `--editor` only for a human-controlled terminal.
+4. Validate the intended write with `--dry-run`.
+5. Write the draft, then fetch it once to verify the stored result.
+
+```bash
+lixblogs blog create --file post.md --title "Title" --tag topic --dry-run --json --no-input
+lixblogs blog create --file post.md --title "Title" --tag topic --json --no-input
+lixblogs blog edit BLOG_ID --file post.md --dry-run --json --no-input
+lixblogs blog edit BLOG_ID --file post.md --json --no-input
+```
+
+Metadata-only revisions use `--title`, `--subtitle`, `--slug`, repeatable `--tag`, `--emoji`, `--cover`, `--publication`, and `--collection`. Content inputs `--file`, `--stdin`, `--content`, and `--editor` are mutually exclusive.
+
+## Recovery
+
+- Exit `2`: correct command syntax; never guess a flag.
+- Exit `3` / `revision_conflict`: read `details.localPath` and `details.serverPath`, preserve both authors' changes, obtain creator approval for ambiguous merges, then retry with `--etag details.serverEtag`.
+- Exit `4` / authentication or scope failure: stop and request the named login/scope action.
+- A request ID in an error is diagnostic metadata; report it without exposing credentials.
+
+This skill ends at a reviewed draft. Use the separate `lixblogs-publish` skill for any public-state change.

package/skills/lixblogs-author/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "LixBlogs Author"
+  short_description: "Draft and revise LixBlogs posts safely"
+  brand_color: "#8B5CF6"
+  default_prompt: "Use $lixblogs-author to prepare or revise a LixBlogs draft through the CLI."
+policy:
+  allow_implicit_invocation: true

package/skills/lixblogs-editorial/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: lixblogs-editorial
+description: Manage LixBlogs collaborators, invitations, review roles, and editorial permissions through the supported CLI. Use when an agent must inspect a blog team, invite a reviewer or editor, change a role, resolve an invitation, or explain deferred collaboration notifications.
+---
+
+# LixBlogs editorial
+
+Use `@elixpo/lixblogs-cli` 1.2.0 or newer. Automation must include `--json --no-input`. Never use D1, browser cookies, passwords, raw credentials, or direct API calls.
+
+## Authority model
+
+- `viewer`: review/read authority only; cannot edit or publish.
+- `editor`: may edit after accepting. Publishing still requires the separate publish OAuth scope and an explicit publishing decision.
+- `admin`: may edit and manage collaborators after accepting. Publishing remains a separate operation.
+- Blog owner and eligible organization managers may manage the team.
+
+Read workflows require `lixblogs:collaboration:read`. Invitations, role changes, acceptance, decline, and removal require `lixblogs:collaboration:write`. Do not request `lixblogs:blog:publish` unless the user separately asks to publish.
+
+## Inspect
+
+```bash
+lixblogs whoami --json --no-input
+lixblogs collab list BLOG_ID --json --no-input
+lixblogs collab invitations --json --no-input
+```
+
+Invitation output reports `notificationState`. `deferred_until_publish` means the draft invitation exists but its user notification is intentionally withheld until the blog has a published reader URL.
+
+## Mutations
+
+State the target user, blog, role, and consequence. Obtain explicit approval before passing `--yes`. Run `--dry-run` first.
+
+```bash
+lixblogs collab invite BLOG_ID --user USERNAME --role viewer --dry-run --json --no-input
+lixblogs collab invite BLOG_ID --user USERNAME --role viewer --yes --json --no-input
+lixblogs collab role BLOG_ID --user USERNAME_OR_ID --role editor --yes --json --no-input
+lixblogs collab remove BLOG_ID --user USERNAME_OR_ID --yes --json --no-input
+lixblogs collab accept BLOG_ID --yes --json --no-input
+lixblogs collab accept BLOG_ID --hide-on-profile --yes --json --no-input
+lixblogs collab decline BLOG_ID --yes --json --no-input
+```
+
+Omitting `--user` from `collab remove` removes the current identity from that blog. Never interpret a review request as permission to grant editor/admin access, accept an invitation, publish, or remove someone.
+
+## Recovery
+
+- Exit `5`: approval is missing. Ask rather than retrying.
+- `role_forbidden`: report the current role and stop; do not probe another tenant or identity.
+- `collaborator_limit_reached`: do not remove someone automatically to make space.
+- `invitation_not_found`: refresh `collab invitations`; it may have been resolved elsewhere.
+- Authentication/scope failure: request only the reported collaboration scope.
+- Include request IDs in failure reports and never expose credentials.
+
+Use `lixblogs-author` for draft content and `lixblogs-publish` only after separate publication approval.

package/skills/lixblogs-editorial/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "LixBlogs Editorial"
+  short_description: "Manage reviewers and collaborators safely"
+  brand_color: "#8B5CF6"
+  default_prompt: "Use $lixblogs-editorial to inspect or manage a LixBlogs collaboration workflow."
+policy:
+  allow_implicit_invocation: true

package/skills/lixblogs-organizations/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: lixblogs-organizations
+description: Inspect LixBlogs organization memberships, roles, collections, and valid publication targets through the supported CLI. Use when an agent must choose or verify a personal, organization, or collection target without crossing tenant boundaries.
+---
+
+# LixBlogs organizations
+
+Use `@elixpo/lixblogs-cli` 1.2.0 or newer and add `--json --no-input` for automation. Use only CLI commands; never access D1, cookies, passwords, tokens, or endpoints directly.
+
+## Access
+
+This read-only workflow requires `lixblogs:organizations:read`. It does not authorize organization changes or publication. Verify the active identity and scope first:
+
+```bash
+lixblogs whoami --json --no-input
+lixblogs org list --json --no-input
+```
+
+## Resolve a target
+
+1. Use `org list` to obtain authenticated memberships and effective roles.
+2. Use the returned organization ID—not an unverified slug—to inspect it.
+3. Use `org targets` for writable publication targets. It excludes read-only memberships.
+4. If a collection is requested, select its ID only from the target's returned collection list.
+5. Present the chosen tenant, role, and collection to the user before passing `--publication org:ORG_ID` or `--collection COLLECTION_ID` to an authoring command.
+
+```bash
+lixblogs org get ORG_ID --json --no-input
+lixblogs org collections ORG_ID --json --no-input
+lixblogs org members ORG_ID --json --no-input
+lixblogs org targets --json --no-input
+```
+
+Roles `admin`, `maintain`, and `write` may appear as writable. `read` is inspection-only. Never infer access from a public organization page, a slug, a previous run, or user-supplied metadata; the current CLI response is authoritative.
+
+## Safety and recovery
+
+- `org_not_found` also represents inaccessible tenants. Do not probe alternate identifiers.
+- `insufficient_scope`: request only `lixblogs:organizations:read`.
+- A missing target means the current identity cannot publish there; stop instead of falling back to a similarly named organization.
+- Re-run `org targets` immediately before a draft changes publication tenant because memberships and roles can change.
+- Report request IDs for diagnosis without printing credentials.
+
+Use `lixblogs-author` to draft after target selection and `lixblogs-publish` for a separately approved public-state change.

package/skills/lixblogs-organizations/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "LixBlogs Organizations"
+  short_description: "Resolve safe organization publication targets"
+  brand_color: "#8B5CF6"
+  default_prompt: "Use $lixblogs-organizations to verify an organization or collection publishing target."
+policy:
+  allow_implicit_invocation: true

package/skills/lixblogs-publish/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: lixblogs-publish
+description: Safely preview, publish, unpublish, trash, restore, or permanently delete LixBlogs posts through the supported CLI. Use when an agent is asked to change a post's public or deletion state and must enforce explicit approval, revision checks, and recovery guidance.
+---
+
+# LixBlogs publish
+
+Use `@elixpo/lixblogs-cli` 1.2.0 or newer with `--json --no-input`. Never use D1, cookies, raw tokens, or direct HTTP calls.
+
+## Access and approval
+
+| Action | Scope | Consequence |
+| --- | --- | --- |
+| Preview | `lixblogs:blog:read` | No state change |
+| Publish / unpublish | `lixblogs:blog:publish` | Adds or removes public access |
+| Trash / restore | `lixblogs:blog:delete` | Hides or recovers content |
+| Permanent delete | `lixblogs:blog:delete:permanent` | Irreversible removal |
+
+Before a state change, state the target, current state, intended state, and consequence. Obtain explicit user approval. A prior request to draft or edit is not approval to publish or delete. Pass `--yes` only after approval.
+
+## Procedure
+
+1. Verify identity and scopes with `lixblogs whoami --json --no-input`.
+2. Inspect the latest state and ETag:
+
+```bash
+lixblogs blog preview BLOG_ID --json --no-input
+```
+
+3. Preflight the exact operation with `--dry-run`.
+4. Show the consequence and ask for approval if it is not already explicit.
+5. Execute once with `--yes`, `--etag ETAG`, and a stable `--idempotency-key` where accepted.
+6. Report the returned canonical URL and ETag. Fetch once to verify the final state.
+
+```bash
+lixblogs blog publish BLOG_ID --etag ETAG --idempotency-key KEY --dry-run --json --no-input
+lixblogs blog publish BLOG_ID --etag ETAG --idempotency-key KEY --yes --json --no-input
+lixblogs blog unpublish BLOG_ID --etag ETAG --yes --json --no-input
+lixblogs blog trash BLOG_ID --etag ETAG --yes --json --no-input
+lixblogs blog restore BLOG_ID --etag ETAG --yes --json --no-input
+lixblogs blog delete BLOG_ID --etag ETAG --permanent --yes --json --no-input
+```
+
+Trash is the default deletion behavior. Never add `--permanent` unless the user explicitly asks for irreversible deletion after seeing that consequence.
+
+## Conflicts and recovery
+
+- Exit `3` / `revision_conflict`: stop. Fetch the current post, explain that it changed, and request a new decision; never force the stale transition.
+- Exit `5` / `confirmation_required`: obtain explicit approval; do not silently retry.
+- `idempotency_in_progress`: wait for the original request result before retrying with the same key.
+- `idempotency_key_reused`: create a new key only for a genuinely new operation.
+- Authentication or missing-scope errors: request only the named scope.
+- If the response has a request ID, include it in the failure report. Never print credentials.
+
+Use `lixblogs-author` for content changes before returning to this procedure.

package/skills/lixblogs-publish/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "LixBlogs Publish"
+  short_description: "Publish and recover posts with approval"
+  brand_color: "#8B5CF6"
+  default_prompt: "Use $lixblogs-publish to safely change a LixBlogs post's publication state."
+policy:
+  allow_implicit_invocation: true

package/src/api/AnalyticsClient.js

@@ -0,0 +1,40 @@
+import { BlogApiError } from './BlogClient.js';
+
+async function parseResponse(response) {
+  let payload;
+  try { payload = await response.json(); } catch { payload = null; }
+  if (!response.ok || payload?.error) {
+    throw new BlogApiError(
+      payload?.error?.code || `http_${response.status}`,
+      payload?.error?.message || `LixBlogs returned HTTP ${response.status}.`,
+      { status: response.status, requestId: payload?.error?.requestId || response.headers.get('x-request-id'), details: payload?.error?.details },
+    );
+  }
+  return payload;
+}
+
+export class AnalyticsClient {
+  constructor(authenticatedClient) {
+    this.http = authenticatedClient;
+  }
+
+  async query(options = {}) {
+    const scope = options.scope || 'personal';
+    await this.http.requireScopes([
+      'lixblogs:analytics:read',
+      ...(scope.startsWith('org:') ? ['lixblogs:organizations:read'] : []),
+    ]);
+    const query = new URLSearchParams({
+      scope,
+      range: options.range || (options.from || options.to ? 'custom' : '30d'),
+      dimension: options.dimension || 'overview',
+      limit: String(options.limit || 20),
+    });
+    if (options.from) query.set('from', options.from);
+    if (options.to) query.set('to', options.to);
+    if (options.cursor) query.set('cursor', options.cursor);
+    return parseResponse(await this.http.request(`/api/v1/analytics?${query}`, {
+      headers: { accept: 'application/json' },
+    }));
+  }
+}

package/src/api/BlogClient.js

@@ -66,6 +66,11 @@ export class BlogClient {
     if (typeof this.http.requireScopes === 'function') await this.http.requireScopes(scopes);
   }
 
+  async whoami() {
+    await this.requireScopes(['lixblogs:profile:read']);
+    return (await this.request('/api/v1/me')).payload.data;
+  }
+
   async list({ status = 'all', limit = 20, cursor } = {}) {
     await this.requireScopes(['lixblogs:blog:read']);
     const query = new URLSearchParams({ status, limit: String(limit) });

package/src/api/CollaborationClient.js

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import { BlogApiError } from './BlogClient.js';
+
+async function parseResponse(response) {
+  let payload;
+  try { payload = await response.json(); } catch { payload = null; }
+  if (!response.ok || payload?.error) {
+    throw new BlogApiError(payload?.error?.code || `http_${response.status}`, payload?.error?.message || `LixBlogs returned HTTP ${response.status}.`, {
+      status: response.status,
+      requestId: payload?.error?.requestId || response.headers.get('x-request-id'),
+      details: payload?.error?.details,
+    });
+  }
+  return payload.data;
+}
+
+export class CollaborationClient {
+  constructor(authenticatedClient) {
+    this.http = authenticatedClient;
+  }
+
+  async request(path, options = {}) {
+    const response = await this.http.request(path, {
+      ...options,
+      headers: {
+        accept: 'application/json',
+        ...(options.body ? { 'content-type': 'application/json' } : {}),
+        ...options.headers,
+      },
+    });
+    return parseResponse(response);
+  }
+
+  async list(blogId) {
+    await this.http.requireScopes(['lixblogs:collaboration:read']);
+    return this.request(`/api/v1/blogs/${encodeURIComponent(blogId)}/collaborators`);
+  }
+
+  async invitations() {
+    await this.http.requireScopes(['lixblogs:collaboration:read']);
+    return this.request('/api/v1/collaboration/invitations');
+  }
+
+  async invite(blogId, { user, role, idempotencyKey = randomUUID() }) {
+    await this.http.requireScopes(['lixblogs:collaboration:write']);
+    return this.request(`/api/v1/blogs/${encodeURIComponent(blogId)}/collaborators`, {
+      method: 'POST', headers: { 'idempotency-key': idempotencyKey }, body: JSON.stringify({ user, role }),
+    });
+  }
+
+  async role(blogId, { user, role, idempotencyKey = randomUUID() }) {
+    await this.http.requireScopes(['lixblogs:collaboration:write']);
+    return this.request(`/api/v1/blogs/${encodeURIComponent(blogId)}/collaborators`, {
+      method: 'PATCH', headers: { 'idempotency-key': idempotencyKey }, body: JSON.stringify({ user, role }),
+    });
+  }
+
+  async remove(blogId, { user, idempotencyKey = randomUUID() } = {}) {
+    await this.http.requireScopes(['lixblogs:collaboration:write']);
+    return this.request(`/api/v1/blogs/${encodeURIComponent(blogId)}/collaborators`, {
+      method: 'DELETE', headers: { 'idempotency-key': idempotencyKey }, body: JSON.stringify({ ...(user ? { user } : {}) }),
+    });
+  }
+
+  async resolveInvitation(blogId, { action, showOnProfile = true, idempotencyKey = randomUUID() }) {
+    await this.http.requireScopes(['lixblogs:collaboration:write']);
+    return this.request('/api/v1/collaboration/invitations', {
+      method: 'POST',
+      headers: { 'idempotency-key': idempotencyKey },
+      body: JSON.stringify({ blogId, action, showOnProfile }),
+    });
+  }
+}

package/src/api/OrgClient.js

@@ -0,0 +1,158 @@
+import { BlogApiError } from "./BlogClient.js";
+
+async function parseResponse(response) {
+    let payload;
+    try {
+        payload = await response.json();
+    } catch {
+        payload = null;
+    }
+    if (!response.ok || payload?.error) {
+        throw new BlogApiError(
+            payload?.error?.code || `http_${response.status}`,
+            payload?.error?.message ||
+                `LixBlogs returned HTTP ${response.status}.`,
+            {
+                status: response.status,
+                requestId:
+                    payload?.error?.requestId ||
+                    response.headers.get("x-request-id"),
+                details: payload?.error?.details,
+            },
+        );
+    }
+    return { payload, etag: response.headers.get("etag") };
+}
+
+export class OrgClient {
+    constructor(
+        authenticatedClient,
+        {
+            sleep = (milliseconds) =>
+                new Promise((resolve) => setTimeout(resolve, milliseconds)),
+        } = {},
+    ) {
+        this.http = authenticatedClient;
+        this.sleep = sleep;
+    }
+
+    async request(path, options = {}) {
+        const requestOptions = {
+            ...options,
+            headers: {
+                accept: "application/json",
+                ...(options.body ? { "content-type": "application/json" } : {}),
+                ...options.headers,
+            },
+        };
+        const method = requestOptions.method || "GET";
+        const retryable = method === "GET";
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                const response = await this.http.request(path, requestOptions);
+                if (
+                    retryable &&
+                    attempt === 0 &&
+                    (response.status === 429 || response.status >= 500)
+                ) {
+                    const seconds = Math.min(
+                        2,
+                        Number.parseInt(
+                            response.headers.get("retry-after") || "1",
+                            10,
+                        ) || 1,
+                    );
+                    await this.sleep(seconds * 1000);
+                    continue;
+                }
+                return parseResponse(response);
+            } catch (error) {
+                if (
+                    !retryable ||
+                    attempt > 0 ||
+                    error instanceof BlogApiError ||
+                    error?.code
+                )
+                    throw error;
+                await this.sleep(250);
+            }
+        }
+        throw new BlogApiError(
+            "request_failed",
+            "The LixBlogs request failed after retrying.",
+        );
+    }
+
+    async requireScopes(scopes) {
+        if (typeof this.http.requireScopes === "function")
+            await this.http.requireScopes(scopes);
+    }
+
+    async list() {
+        await this.requireScopes(["lixblogs:organizations:read"]);
+        return (await this.request("/api/v1/orgs")).payload;
+    }
+
+    async get(id) {
+        if (!id) throw new Error("An organization ID or handle is required.");
+        await this.requireScopes(["lixblogs:organizations:read"]);
+        return (await this.request(`/api/v1/orgs/${encodeURIComponent(id)}`))
+            .payload.data;
+    }
+
+    async collections(id) {
+        if (!id) throw new Error("An organization ID or handle is required.");
+        await this.requireScopes(["lixblogs:organizations:read"]);
+        return (
+            await this.request(
+                `/api/v1/orgs/${encodeURIComponent(id)}/collections`,
+            )
+        ).payload.data;
+    }
+
+    async members(id) {
+        if (!id) throw new Error("An organization ID or handle is required.");
+        await this.requireScopes(["lixblogs:organizations:read"]);
+        return (
+            await this.request(`/api/v1/orgs/${encodeURIComponent(id)}/members`)
+        ).payload.data;
+    }
+
+    async targets() {
+        await this.requireScopes(["lixblogs:organizations:read"]);
+        const orgsList = await this.list();
+        const orgs = orgsList?.data || [];
+        const writableOrgs = orgs.filter((org) => org.canWrite);
+
+        const orgTargets = await Promise.all(
+            writableOrgs.map(async (org) => {
+                let cols = [];
+                try {
+                    cols = await this.collections(org.id);
+                } catch {
+                    cols = [];
+                }
+                return {
+                    target: `org:${org.id}`,
+                    orgId: org.id,
+                    slug: org.slug,
+                    name: org.name,
+                    role: org.role,
+                    collections: cols.map((col) => ({
+                        id: col.id,
+                        slug: col.slug,
+                        name: col.name,
+                    })),
+                };
+            }),
+        );
+
+        return {
+            personal: {
+                target: "personal",
+                name: "Personal Blog",
+            },
+            organizations: orgTargets,
+        };
+    }
+}

package/src/auth/AuthenticatedClient.js

@@ -20,6 +20,17 @@ export class LoginRequiredError extends Error {
   }
 }
 
+export class ApiContractUnavailableError extends Error {
+  constructor(status, contentType) {
+    super("The configured LixBlogs origin is not serving the API v1 JSON contract.");
+    this.name = "ApiContractUnavailableError";
+    this.code = "api_contract_unavailable";
+    this.status = status;
+    this.details = { contentType: contentType || "unknown" };
+    this.hint = "Deploy the LixBlogs API v1 stack, or select an origin that exposes /api/v1.";
+  }
+}
+
 export class AuthenticatedClient {
   constructor({
     provider,
@@ -99,6 +110,10 @@ export class AuthenticatedClient {
       credentials = await this.credentials({ forceRefresh: true });
       response = await send();
     }
+    const contentType = response.headers.get("content-type") || "";
+    if (!contentType.toLowerCase().includes("application/json")) {
+      throw new ApiContractUnavailableError(response.status, contentType);
+    }
     return response;
   }
 

package/src/auth/ElixpoAuthProvider.js

@@ -100,7 +100,7 @@ export class ElixpoAuthProvider extends AuthProvider {
     accountsBaseUrl = "https://accounts.elixpo.com",
     clientId = "lixblogs-cli-prod",
     audience = "blogs.elixpo.com",
-    cliVersion = "1.1.0",
+    cliVersion = "1.2.0",
     fetchImpl = globalThis.fetch,
     timeoutMs = DEFAULT_TIMEOUT_MS,
   } = {}) {

package/src/cli/contract.js

@@ -0,0 +1,46 @@
+export const EXIT_CODES = Object.freeze({
+  OK: 0,
+  ERROR: 1,
+  USAGE: 2,
+  CONFLICT: 3,
+  AUTH: 4,
+  CONFIRMATION: 5,
+});
+
+const TOP_LEVEL_ALIASES = Object.freeze({
+  login: ['auth', 'login'],
+  logout: ['auth', 'logout'],
+  whoami: ['auth', 'whoami'],
+  profiles: ['auth', 'profiles'],
+  use: ['auth', 'use'],
+});
+
+export function normalizeCommand(positionals) {
+  const [command, ...rest] = positionals;
+  const alias = TOP_LEVEL_ALIASES[command];
+  return alias ? [...alias, ...rest] : positionals;
+}
+
+export function errorEnvelope(error, fallbackCode = 'cli_error') {
+  if (error && typeof error === 'object' && error.error && !Array.isArray(error.error)) return error;
+  const value = error && typeof error === 'object' ? error : { message: String(error || 'Command failed.') };
+  return {
+    ok: false,
+    error: {
+      code: value.code || fallbackCode,
+      message: value.message || 'Command failed.',
+      hint: value.hint || null,
+      requestId: value.requestId || null,
+      ...(value.details ? { details: value.details } : {}),
+    },
+  };
+}
+
+export function requireConfirmation(options, action) {
+  if (options.yes) return;
+  const error = new Error(`${action} requires --yes in non-interactive operation.`);
+  error.code = 'confirmation_required';
+  error.hint = `Review the operation, then run it again with --yes.`;
+  error.exitCode = EXIT_CODES.CONFIRMATION;
+  throw error;
+}

package/src/cli/ui.js

@@ -0,0 +1,54 @@
+const ANSI = Object.freeze({
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  dim: "\u001b[2m",
+  violet: "\u001b[38;5;141m",
+  green: "\u001b[38;5;42m",
+});
+
+export function colorEnabled(stream = process.stdout, env = process.env) {
+  return Boolean(stream.isTTY) && env.NO_COLOR === undefined && env.TERM !== "dumb";
+}
+
+function paint(value, code, enabled) {
+  return enabled ? `${code}${value}${ANSI.reset}` : value;
+}
+
+export function loginChallenge({ url, code, expiresInSeconds, profile, interactive, color = false }) {
+  const title = `${paint("◆", ANSI.violet, color)} ${paint("LixBlogs", ANSI.bold, color)}`;
+  const instruction = interactive
+    ? "Press Enter to open here, or use the URL on another device."
+    : "Open the URL in any browser and approve this device.";
+  return [
+    "",
+    `  ${title}`,
+    `  ${paint("Device login", ANSI.dim, color)}`,
+    "  ─────────────────────────────────────────",
+    `  URL      ${url}`,
+    `  Code     ${paint(code, ANSI.bold, color)}`,
+    `  Expires  ${Math.ceil(expiresInSeconds / 60)} min`,
+    profile
+      ? `  Profile  ${profile} ${paint("(local credential slot)", ANSI.dim, color)}`
+      : `  Profile  ${paint("your Accounts username after approval", ANSI.dim, color)}`,
+    "",
+    `  ${instruction}`,
+    "  No localhost callback or exposed port is required.",
+    "",
+  ].join("\n");
+}
+
+export function successLine(message, color = false) {
+  return `  ${paint("✓", ANSI.green, color)} ${message}`;
+}
+
+export function listenForEnter({ input = process.stdin, open, url }) {
+  if (!input.isTTY || typeof open !== "function") return () => {};
+  const onData = () => { Promise.resolve(open(url)).catch(() => {}); };
+  input.setEncoding?.("utf8");
+  input.once("data", onData);
+  input.resume?.();
+  return () => {
+    input.off?.("data", onData);
+    input.pause?.();
+  };
+}