@elixpo/lixblogs-cli 1.1.2

package/src/commands/auth/login.js

@@ -0,0 +1,103 @@
+/**
+ * lixblogs auth login
+ *
+ * Per #135:
+ * - Display verification URL, user code, expiry, and polling status;
+ *   optionally open the browser
+ * - Support multiple named accounts/profiles
+ * - Destructive and publishing scopes require clear consent
+ *
+ * This command is deliberately provider-agnostic — it only calls the
+ * AuthProvider interface, never a concrete implementation. In dev/tests
+ * this is wired to MockAuthProvider; production wiring goes through
+ * productionGate.assertProviderAllowed() before this ever runs (see
+ * bin/lixblogs.mjs for where that check happens).
+ */
+
+import { redactErrorMessage } from "../../config/redact.js";
+
+/**
+ * @param {Object} params
+ * @param {import("../../auth/AuthProvider.js").AuthProvider} params.provider
+ * @param {import("../../config/CredentialStore.js").CredentialStore} params.credentialStore
+ * @param {string} params.profileId - which named profile this login is for
+ * @param {string[]} params.scopes - scopes being requested
+ * @param {(url: string) => Promise<void>} [params.openBrowser] - optional browser opener
+ * @param {(ms: number) => Promise<void>} [params.sleep] - injectable for tests
+ * @param {(...args: any[]) => void} [params.onStatus] - callback for UI updates (verification URL, polling status, etc.)
+ * @returns {Promise<{ ok: true, profileId: string } | { ok: false, reason: string }>}
+ */
+export async function authLogin({
+  provider,
+  credentialStore,
+  profileId,
+  scopes,
+  openBrowser,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  onStatus = () => {},
+}) {
+  let deviceCode;
+  try {
+    deviceCode = await provider.requestDeviceCode({ scopes });
+  } catch (err) {
+    return { ok: false, reason: redactErrorMessage(err.message) };
+  }
+
+  onStatus({
+    type: "verification_pending",
+    verificationUri: deviceCode.verificationUri,
+    verificationUriComplete: deviceCode.verificationUriComplete,
+    userCode: deviceCode.userCode,
+    expiresInSeconds: deviceCode.expiresInSeconds,
+  });
+
+  if (openBrowser) {
+    await openBrowser(deviceCode.verificationUriComplete || deviceCode.verificationUri);
+  }
+
+  let pollIntervalMs = deviceCode.pollIntervalSeconds * 1000;
+  const deadline = Date.now() + deviceCode.expiresInSeconds * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs);
+
+    let result;
+    try {
+      result = await provider.pollDeviceCode({ deviceCode: deviceCode.deviceCode });
+    } catch (err) {
+      return { ok: false, reason: redactErrorMessage(err.message) };
+    }
+
+    if (result.status === "approved") {
+      await credentialStore.set(profileId, {
+        accessToken: result.token.accessToken,
+        refreshToken: result.token.refreshToken,
+        expiresAt: Date.now() + result.token.expiresInSeconds * 1000,
+        scopes: result.token.scopes,
+      });
+      onStatus({ type: "approved" });
+      return { ok: true, profileId };
+    }
+
+    if (result.status === "denied") {
+      onStatus({ type: "denied" });
+      return { ok: false, reason: "Login was denied." };
+    }
+
+    if (result.status === "expired") {
+      onStatus({ type: "expired" });
+      return { ok: false, reason: "Device code expired before login was approved." };
+    }
+
+    if (result.status === "slow_down") {
+      pollIntervalMs += result.pollIntervalIncreaseSeconds * 1000;
+      onStatus({ type: "slow_down", newIntervalMs: pollIntervalMs });
+      continue;
+    }
+
+    // status === "pending" — keep polling
+    onStatus({ type: "pending" });
+  }
+
+  return { ok: false, reason: "Device code expired before login was approved." };
+}

package/src/commands/auth/logout.js

@@ -0,0 +1,21 @@
+/**
+ * lixblogs auth logout
+ *
+ * Clears locally stored credentials for a profile. This is a *local*
+ * operation — it does not revoke the token server-side (that's `revoke`).
+ * A user who just wants to stop using this machine, without invalidating
+ * the token everywhere, should be able to do that — this command is that
+ * lighter-weight action. See revoke.js for the destructive, server-side
+ * equivalent.
+ */
+
+/**
+ * @param {Object} params
+ * @param {import("../../config/CredentialStore.js").CredentialStore} params.credentialStore
+ * @param {string} params.profileId
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function authLogout({ credentialStore, profileId }) {
+  await credentialStore.delete(profileId);
+  return { ok: true };
+}

package/src/commands/auth/profiles.js

@@ -0,0 +1,27 @@
+/** List known profiles without exposing credentials. */
+export async function authProfiles({ credentialStore, profileRegistry }) {
+  const activeProfile = await profileRegistry.getActive();
+  const profileIds = await credentialStore.listProfiles();
+  const profiles = [];
+  for (const profileId of profileIds) {
+    const credentials = await credentialStore.get(profileId);
+    profiles.push({
+      profileId,
+      active: profileId === activeProfile,
+      loggedIn: Boolean(credentials),
+      expired: credentials ? Date.now() >= credentials.expiresAt : undefined,
+      scopes: credentials?.scopes || [],
+    });
+  }
+  return { activeProfile, profiles };
+}
+
+/** Select the profile used when --profile is omitted. */
+export async function authUse({ credentialStore, profileRegistry, profileId }) {
+  const credentials = await credentialStore.get(profileId);
+  if (!credentials) {
+    return { ok: false, reason: `Profile "${profileId}" is not logged in.` };
+  }
+  await profileRegistry.setActive(profileId);
+  return { ok: true, profileId };
+}

package/src/commands/auth/revoke.js

@@ -0,0 +1,45 @@
+/**
+ * lixblogs auth revoke
+ *
+ * Revokes the token server-side (via the AuthProvider) AND clears local
+ * storage. This is destructive — per #135, "destructive and publishing
+ * scopes require clear consent" and "destructive commands cannot run
+ * accidentally in a non-interactive session."
+ *
+ * This function does not itself prompt — that's the CLI shell's job
+ * (interactive confirmation prompt, or requiring an explicit --yes flag in
+ * non-interactive mode). This function requires the caller to have already
+ * obtained consent and pass confirmed: true; if confirmed is not exactly
+ * true, it refuses to proceed. This makes "forgot to check for consent"
+ * impossible to do accidentally at the call site.
+ */
+
+/**
+ * @param {Object} params
+ * @param {import("../../auth/AuthProvider.js").AuthProvider} params.provider
+ * @param {import("../../config/CredentialStore.js").CredentialStore} params.credentialStore
+ * @param {string} params.profileId
+ * @param {boolean} params.confirmed - must be exactly `true`; caller is
+ *   responsible for having obtained real user consent before setting this.
+ * @returns {Promise<{ ok: true } | { ok: false, reason: string }>}
+ */
+export async function authRevoke({ provider, credentialStore, profileId, confirmed }) {
+  if (confirmed !== true) {
+    return {
+      ok: false,
+      reason:
+        "Revoke was not confirmed. This is a destructive action and requires " +
+        "explicit confirmation (interactive prompt, or --yes in a non-interactive session).",
+    };
+  }
+
+  const credentials = await credentialStore.get(profileId);
+  if (!credentials) {
+    return { ok: false, reason: `No stored credentials for profile "${profileId}".` };
+  }
+
+  await provider.revoke({ token: credentials.refreshToken });
+  await credentialStore.delete(profileId);
+
+  return { ok: true };
+}

package/src/commands/auth/status.js

@@ -0,0 +1,33 @@
+/**
+ * lixblogs auth status
+ *
+ * Shows whether the given profile (or all profiles) is logged in, and
+ * whether its token is expired. Never prints the token itself — only
+ * derived, safe-to-display metadata (per #135's redaction requirement).
+ */
+
+/**
+ * @param {Object} params
+ * @param {import("../../config/CredentialStore.js").CredentialStore} params.credentialStore
+ * @param {string} [params.profileId] - if omitted, reports on all profiles
+ * @returns {Promise<Array<{ profileId: string, loggedIn: boolean, expired?: boolean, scopes?: string[] }>>}
+ */
+export async function authStatus({ credentialStore, profileId }) {
+  const profileIds = profileId ? [profileId] : await credentialStore.listProfiles();
+
+  const results = [];
+  for (const id of profileIds) {
+    const credentials = await credentialStore.get(id);
+    if (!credentials) {
+      results.push({ profileId: id, loggedIn: false });
+      continue;
+    }
+    results.push({
+      profileId: id,
+      loggedIn: true,
+      expired: Date.now() >= credentials.expiresAt,
+      scopes: credentials.scopes,
+    });
+  }
+  return results;
+}

package/src/commands/blog/index.js

@@ -0,0 +1,81 @@
+import { blocksToMarkdown } from '../../content/markdown.js';
+import { BlogApiError } from '../../api/BlogClient.js';
+import { metadataFromOptions, resolveMarkdownInput } from './input.js';
+import { validateBlogInput } from '../../content/validate.js';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export async function blogList({ client, options }) {
+  return client.list({ status: options.status, limit: options.limit, cursor: options.cursor });
+}
+
+export async function blogGet({ client, id }) {
+  if (!id) throw new Error('A blog ID is required.');
+  const blog = await client.get(id);
+  return { ...blog, markdown: blocksToMarkdown(blog.content) };
+}
+
+export async function blogCreate({ client, options, stdin }) {
+  const source = await resolveMarkdownInput(options, { stdin });
+  const input = { ...metadataFromOptions(options), content: source?.blocks || [] };
+  validateBlogInput(input);
+  if (options['dry-run']) return { dryRun: true, input, markdown: source?.markdown || '' };
+  return client.create(input, { idempotencyKey: options['idempotency-key'] });
+}
+
+export async function blogEdit({ client, id, options, stdin }) {
+  if (!id) throw new Error('A blog ID is required.');
+  const current = await client.get(id);
+  const source = await resolveMarkdownInput(options, { stdin, initial: blocksToMarkdown(current.content) });
+  const input = { ...metadataFromOptions(options), ...(source ? { content: source.blocks } : {}) };
+  if (!Object.keys(input).length) throw new Error('No blog changes were provided.');
+  validateBlogInput(input);
+  if (options['dry-run']) return { dryRun: true, id, etag: current.etag, input, markdown: source?.markdown };
+  try {
+    return await client.update(id, input, { etag: options.etag || current.etag });
+  } catch (error) {
+    if (!(error instanceof BlogApiError) || error.code !== 'revision_conflict') throw error;
+    const server = await client.get(id);
+    const directory = options.conflictDirectory || path.resolve('.lixblogs-conflicts');
+    await fs.mkdir(directory, { recursive: true });
+    const safeId = id.replace(/[^A-Za-z0-9._-]/g, '_');
+    const localPath = path.join(directory, `${safeId}-local.json`);
+    const serverPath = path.join(directory, `${safeId}-server.md`);
+    await Promise.all([
+      fs.writeFile(localPath, JSON.stringify(input, null, 2), { mode: 0o600 }),
+      fs.writeFile(serverPath, blocksToMarkdown(server.content), { mode: 0o600 }),
+    ]);
+    error.details = { ...error.details, localPath, serverPath, serverEtag: server.etag };
+    throw error;
+  }
+}
+
+export async function blogPublish({ client, id, options }) {
+  if (!id) throw new Error('A blog ID is required.');
+  const current = await client.get(id);
+  validateBlogInput(current, { publishing: true });
+  if (options['dry-run']) return { dryRun: true, id, from: current.status, to: 'published' };
+  return client.publish(id, { etag: options.etag || current.etag, idempotencyKey: options['idempotency-key'] });
+}
+
+export async function blogUnpublish({ client, id, options }) {
+  if (!id) throw new Error('A blog ID is required.');
+  const current = await client.get(id);
+  if (options['dry-run']) return { dryRun: true, id, from: current.status, to: 'draft' };
+  return client.unpublish(id, { etag: options.etag || current.etag });
+}
+
+export async function blogDelete({ client, id, options }) {
+  if (!id) throw new Error('A blog ID is required.');
+  if (!options.yes) throw new Error('Deletion requires --yes. Trash is the default; add --permanent for irreversible deletion.');
+  const current = await client.get(id);
+  if (options['dry-run']) return { dryRun: true, id, permanent: options.permanent };
+  return client.delete(id, { etag: options.etag || current.etag, permanent: options.permanent });
+}
+
+export async function blogRestore({ client, id, options }) {
+  if (!id) throw new Error('A blog ID is required.');
+  const current = await client.get(id);
+  if (options['dry-run']) return { dryRun: true, id, restoreTo: current.preDeleteStatus || 'draft' };
+  return client.restore(id, { etag: options.etag || current.etag });
+}

package/src/commands/blog/input.js

@@ -0,0 +1,59 @@
+import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { markdownToBlocks } from '../../content/markdown.js';
+
+async function stdinText(stream) {
+  let value = '';
+  stream.setEncoding('utf8');
+  for await (const chunk of stream) value += chunk;
+  return value;
+}
+
+async function editText(initial = '', editor = process.env.EDITOR || process.env.VISUAL) {
+  if (!editor) throw new Error('$EDITOR or $VISUAL must be set when using --editor.');
+  const directory = await fs.mkdtemp(path.join(tmpdir(), 'lixblogs-'));
+  const filename = path.join(directory, 'post.md');
+  await fs.writeFile(filename, initial, { mode: 0o600 });
+  try {
+    await new Promise((resolve, reject) => {
+      const child = spawn(editor, [filename], { stdio: 'inherit', shell: true });
+      child.once('error', reject);
+      child.once('exit', (code) => code === 0 ? resolve() : reject(new Error(`Editor exited with code ${code}.`)));
+    });
+    return await fs.readFile(filename, 'utf8');
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+}
+
+export async function resolveMarkdownInput(options, { stdin = process.stdin, initial = '' } = {}) {
+  const selected = [options.file !== undefined, options.stdin, options.content !== undefined, options.editor]
+    .filter(Boolean).length;
+  if (selected > 1) throw new Error('Use only one of --file, --stdin, --content, or --editor.');
+  if (!selected) return null;
+  let markdown;
+  if (options.file !== undefined) markdown = await fs.readFile(path.resolve(options.file), 'utf8');
+  else if (options.stdin) markdown = await stdinText(stdin);
+  else if (options.content !== undefined) markdown = options.content;
+  else markdown = await editText(initial);
+  return { markdown, blocks: markdownToBlocks(markdown) };
+}
+
+export function metadataFromOptions(options) {
+  const input = {};
+  const mappings = {
+    title: 'title', subtitle: 'subtitle', slug: 'slug', emoji: 'emoji',
+    publication: 'publishedAs', collection: 'collectionId', cover: 'coverUrl',
+  };
+  for (const [option, field] of Object.entries(mappings)) {
+    if (options[option] !== undefined) input[field] = options[option];
+  }
+  if (options.tag !== undefined) input.tags = options.tag;
+  if (options['member-only']) input.memberOnly = true;
+  if (options['no-member-only']) input.memberOnly = false;
+  if (options.secret) input.secret = true;
+  if (options['not-secret']) input.secret = false;
+  return input;
+}

package/src/config/CredentialStore.js

@@ -0,0 +1,142 @@
+/**
+ * CredentialStore — abstracts OS keychain access for tokens.
+ *
+ * Per #135: "Store credentials in the OS keychain; require an explicit
+ * opt-in fallback when unavailable." This means:
+ *   - Default backend must be the real OS keychain (macOS Keychain,
+ *     Windows Credential Manager, Linux Secret Service/libsecret)
+ *   - Falling back to anything else (e.g. an encrypted file) requires the
+ *     user to explicitly opt in at the moment it's needed — never silently
+ *
+ * This file defines the interface + a real backend wrapper. The actual
+ * OS-level library (e.g. a keytar-alternative) is expected to be wired in
+ * here; this scaffold ships with the interface, an in-memory store (tests
+ * only — never for real use), and the opt-in-gated fallback path so the
+ * commands built on top of this don't need to change once the real
+ * keychain library is chosen and added as a dependency.
+ */
+
+export class CredentialStoreUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CredentialStoreUnavailableError";
+  }
+}
+
+export class CredentialStore {
+  /**
+   * @param {string} _profileId
+   * @returns {Promise<{ accessToken: string, refreshToken: string, expiresAt: number, scopes: string[] } | null>}
+   */
+  async get(_profileId) {
+    throw new Error("CredentialStore.get must be implemented by subclass");
+  }
+
+  /**
+   * @param {string} _profileId
+   * @param {{ accessToken: string, refreshToken: string, expiresAt: number, scopes: string[] }} _credentials
+   * @returns {Promise<void>}
+   */
+  async set(_profileId, _credentials) {
+    throw new Error("CredentialStore.set must be implemented by subclass");
+  }
+
+  /**
+   * @param {string} _profileId
+   * @returns {Promise<void>} Must not throw if nothing was stored.
+   */
+  async delete(_profileId) {
+    throw new Error("CredentialStore.delete must be implemented by subclass");
+  }
+
+  /**
+   * @returns {Promise<string[]>} All profile IDs currently holding credentials.
+   */
+  async listProfiles() {
+    throw new Error("CredentialStore.listProfiles must be implemented by subclass");
+  }
+}
+
+/**
+ * In-memory store — for tests only. Never use this for real credential
+ * storage; it exists purely so command logic can be tested without an OS
+ * keychain in CI.
+ */
+export class InMemoryCredentialStore extends CredentialStore {
+  constructor() {
+    super();
+    /** @type {Map<string, object>} */
+    this._store = new Map();
+  }
+
+  async get(profileId) {
+    return this._store.get(profileId) ?? null;
+  }
+
+  async set(profileId, credentials) {
+    this._store.set(profileId, credentials);
+  }
+
+  async delete(profileId) {
+    this._store.delete(profileId);
+  }
+
+  async listProfiles() {
+    return [...this._store.keys()];
+  }
+}
+
+/**
+ * Wraps a real OS-keychain-backed store, enforcing the "explicit opt-in
+ * fallback" rule: if the underlying keychain library reports unavailable
+ * (e.g. no Secret Service running on a headless Linux box), this does NOT
+ * silently fall back — it throws CredentialStoreUnavailableError, and the
+ * calling command is responsible for prompting the user for explicit
+ * opt-in before constructing a fallback store instance.
+ *
+ * @param {CredentialStore} realStore - the actual OS-keychain-backed store
+ */
+export class GatedCredentialStore extends CredentialStore {
+  constructor(realStore) {
+    super();
+    this._realStore = realStore;
+  }
+
+  async get(profileId) {
+    try {
+      return await this._realStore.get(profileId);
+    } catch (err) {
+      throw new CredentialStoreUnavailableError(
+        `OS keychain is unavailable: ${err.message}. Re-run with an explicit ` +
+          `fallback flag if you want to opt in to a less secure storage method.`
+      );
+    }
+  }
+
+  async set(profileId, credentials) {
+    try {
+      await this._realStore.set(profileId, credentials);
+    } catch (err) {
+      throw new CredentialStoreUnavailableError(
+        `OS keychain is unavailable: ${err.message}. Re-run with an explicit ` +
+          `fallback flag if you want to opt in to a less secure storage method.`
+      );
+    }
+  }
+
+  async delete(profileId) {
+    try {
+      await this._realStore.delete(profileId);
+    } catch (err) {
+      throw new CredentialStoreUnavailableError(`OS keychain is unavailable: ${err.message}`);
+    }
+  }
+
+  async listProfiles() {
+    try {
+      return await this._realStore.listProfiles();
+    } catch (err) {
+      throw new CredentialStoreUnavailableError(`OS keychain is unavailable: ${err.message}`);
+    }
+  }
+}