careervivid 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# CareerVivid CLI
+
+Official command-line interface for [CareerVivid](https://careervivid.app) — publish articles, architecture diagrams, and portfolio updates directly from your terminal or an AI coding agent.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Clone and build (one-time setup)
+git clone https://github.com/Jastalk/CareerVivid
+cd CareerVivid/cli
+npm install && npm run build
+
+# 2. Install globally
+npm install -g .
+
+# 3. Authenticate and publish
+cv auth set-key
+cv publish article.md
+```
+
+---
+
+## Installation
+
+```bash
+# Build from source and install globally
+git clone https://github.com/Jastalk/CareerVivid
+cd CareerVivid/cli && npm install && npm run build
+npm install -g .
+
+# If you already have the repo:
+cd path/to/careervivid/cli
+npm install && npm run build && npm install -g .
+```
+
+---
+
+## Authentication
+
+Get your API key at [careervivid.app/#/developer](https://careervivid.app/#/developer).
+
+```bash
+# Interactive setup
+cv auth set-key
+
+# Or pass it directly (no prompts)
+cv auth set-key cv_live_your_key_here
+
+# Verify it works
+cv auth check
+
+# See current config
+cv auth whoami
+```
+
+Your key is stored in `~/.careervividrc.json` with `chmod 600` permissions. It is never printed to stdout.
+
+**Alternatively**, set the `CV_API_KEY` environment variable (takes priority over the config file):
+```bash
+export CV_API_KEY=cv_live_...
+```
+
+---
+
+## Publishing Content
+
+### Publish a Markdown article
+
+```bash
+cv publish article.md
+cv publish article.md --title "My Custom Title" --tags "typescript,firebase,saas"
+```
+
+The title is automatically inferred from the first `# Heading` in your file.
+
+### Publish a Mermaid diagram
+
+```bash
+cv publish diagram.mmd --type whiteboard
+```
+
+Files with `.mmd` or `.mermaid` extensions are automatically detected as Mermaid diagrams.
+
+### Publish from stdin (pipe-friendly for AI agents)
+
+```bash
+cat article.md | cv publish - --title "Architecture Deep Dive"
+echo "# My Post\n\nHello world!" | cv publish - --tags "ai,demo"
+```
+
+### Dry run (validate without publishing)
+
+```bash
+cv publish article.md --dry-run
+```
+
+### Machine-readable JSON output (for AI agents and scripts)
+
+Every command supports `--json`:
+
+```bash
+cv publish article.md --json
+# → {"success":true,"postId":"abc123","url":"https://careervivid.app/community/post/abc123"}
+
+cat article.md | cv publish - --title "Post" --json
+# → {"success":true,"postId":"abc123","url":"..."}
+```
+
+---
+
+## Command Reference
+
+```
+cv publish [file]
+  [file]             Path to a .md / .mmd file, or "-" to read stdin
+  --title <title>    Post title (required for stdin / if no # heading)
+  --type             article | whiteboard  (default: inferred)
+  --format           markdown | mermaid    (default: inferred from extension)
+  --tags <tags>      Comma-separated tags, max 5
+  --cover <url>      URL to a cover image
+  --dry-run          Validate without publishing
+  --json             Machine-readable output
+
+cv auth set-key [apiKey]
+cv auth check
+cv auth whoami
+cv auth revoke
+
+cv config show
+cv config get <key>         (keys: apiKey, apiUrl)
+cv config set <key> <val>
+```
+
+---
+
+## AI Agent & MCP Integration
+
+### With Cursor / Claude Desktop (MCP)
+
+The [MCP server](../mcp-server/) is the recommended way to integrate with AI coding agents. See `mcp-server/README.md`.
+
+### Direct CLI from an AI agent
+
+```bash
+# Agent publishes an article it just wrote:
+echo "${ARTICLE_CONTENT}" | cv publish - \
+  --title "${TITLE}" \
+  --tags "${TAGS}" \
+  --json
+
+# Agent parses the JSON response:
+# {"success":true,"postId":"abc123","url":"https://careervivid.app/community/post/abc123"}
+```
+
+For full agentic pipelines, prefer the MCP server — it integrates natively with AI tool calling.
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CV_API_KEY` | API key (overrides config file) |
+| `CV_API_URL` | Override the publish endpoint (for self-hosting or staging) |
+
+---
+
+## Configuration File
+
+Location: `~/.careervividrc.json` (mode 600 — readable only by your user)
+
+```json
+{
+  "apiKey": "cv_live_...",
+  "apiUrl": "https://careervivid.app/api/publish"
+}
+```
+
+---
+
+## Building from Source
+
+```bash
+cd cli
+npm install
+npm run build      # TypeScript → dist/
+node dist/index.js --help
+```
+
+---
+
+## Security
+
+- API keys are **never** written to `stdout` — only `stderr` diagnostics and masked previews
+- The config file is created with `chmod 600`
+- Never commit `~/.careervividrc.json` or `CV_API_KEY` to version control
+- Revoke a compromised key immediately at [careervivid.app/#/developer](https://careervivid.app/#/developer)

package/dist/api.d.ts

@@ -0,0 +1,38 @@
+/**
+ * API client — thin fetch wrapper around the CareerVivid API.
+ *
+ * All functions throw on network errors; on HTTP errors they return
+ * a structured ApiError for clean CLI error messages.
+ */
+export type PostType = "article" | "whiteboard";
+export type DataFormat = "markdown" | "mermaid";
+export interface PublishPayload {
+    type: PostType;
+    dataFormat: DataFormat;
+    title: string;
+    content: string;
+    tags?: string[];
+    coverImage?: string;
+}
+export interface PublishResult {
+    success: boolean;
+    postId: string;
+    url: string;
+    message: string;
+}
+export interface ApiError {
+    isError: true;
+    statusCode: number;
+    message: string;
+    fields?: {
+        field: string;
+        message: string;
+    }[];
+}
+export declare function publishPost(payload: PublishPayload, dryRun?: boolean): Promise<PublishResult | ApiError>;
+export declare function pingAuth(): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+export declare function isApiError(v: unknown): v is ApiError;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAC;AAChD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACrB,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjD;AAsDD,wBAAsB,WAAW,CAC7B,OAAO,EAAE,cAAc,EACvB,MAAM,UAAQ,GACf,OAAO,CAAC,aAAa,GAAG,QAAQ,CAAC,CAiBnC;AAED,wBAAsB,QAAQ,IAAI,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBzE;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,QAAQ,CAEpD"}

package/dist/api.js

@@ -0,0 +1,94 @@
+/**
+ * API client — thin fetch wrapper around the CareerVivid API.
+ *
+ * All functions throw on network errors; on HTTP errors they return
+ * a structured ApiError for clean CLI error messages.
+ */
+import { getApiKey, getApiUrl } from "./config.js";
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function requireApiKey() {
+    const key = getApiKey();
+    if (!key) {
+        throw new Error("No API key configured.\n\n" +
+            "  Run:  cv auth set-key\n" +
+            "  Or:   export CV_API_KEY=cv_live_...\n\n" +
+            "  Get your key at: https://careervivid.app/#/developer");
+    }
+    return key;
+}
+async function apiRequest(method, path, body) {
+    const apiKey = requireApiKey();
+    const baseUrl = getApiUrl().replace(/\/+$/, "");
+    const url = `${baseUrl}${path === "" ? "" : "/" + path}`;
+    const response = await fetch(url, {
+        method,
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": apiKey,
+            "User-Agent": "careervivid-cli/1.0.0",
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await response.text();
+    let parsed = {};
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parsed = { message: text };
+    }
+    if (!response.ok) {
+        return {
+            isError: true,
+            statusCode: response.status,
+            message: parsed.error || parsed.message || `HTTP ${response.status}`,
+            fields: parsed.fields,
+        };
+    }
+    return parsed;
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+export async function publishPost(payload, dryRun = false) {
+    if (dryRun) {
+        // Basic local validation only — don't call the network
+        if (!payload.title || payload.title.trim() === "") {
+            return { isError: true, statusCode: 0, message: "Title is required." };
+        }
+        if (!payload.content || payload.content.trim() === "") {
+            return { isError: true, statusCode: 0, message: "Content is required." };
+        }
+        return {
+            success: true,
+            postId: "dry-run-no-id",
+            url: "https://careervivid.app/community (dry-run — not published)",
+            message: "Dry run passed. No post was created.",
+        };
+    }
+    return apiRequest("POST", "", payload);
+}
+export async function pingAuth() {
+    const apiKey = getApiKey();
+    if (!apiKey)
+        return { ok: false, error: "No API key configured." };
+    // We send a GET (HEAD-like) to the publish endpoint.
+    // The API returns 405 if auth succeeds and only POST is allowed — that's fine.
+    // It returns 401 if auth fails.
+    const apiUrl = getApiUrl().replace(/\/+$/, "");
+    try {
+        const res = await fetch(apiUrl, {
+            method: "GET",
+            headers: { "x-api-key": apiKey, "User-Agent": "careervivid-cli/1.0.0" },
+        });
+        // 405 = Method Not Allowed → the key is valid, but GET is not supported → auth OK
+        // 401 = Unauthorized → bad key
+        if (res.status === 401)
+            return { ok: false, error: "API key is invalid or has been revoked." };
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: `Network error: ${err.message}` };
+    }
+}
+export function isApiError(v) {
+    return typeof v === "object" && v !== null && v.isError === true;
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * cv auth — API key management
+ *
+ * Subcommands:
+ *   cv auth set-key          Interactively prompt for an API key and save it
+ *   cv auth check            Verify the saved key is accepted by the server
+ *   cv auth whoami           Print the identity associated with the key (if supported)
+ *   cv auth revoke           Remove saved API key from config
+ */
+import { Command } from "commander";
+export declare function registerAuthCommand(program: Command): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoJ1D"}

package/dist/commands/auth.js

@@ -0,0 +1,128 @@
+/**
+ * cv auth — API key management
+ *
+ * Subcommands:
+ *   cv auth set-key          Interactively prompt for an API key and save it
+ *   cv auth check            Verify the saved key is accepted by the server
+ *   cv auth whoami           Print the identity associated with the key (if supported)
+ *   cv auth revoke           Remove saved API key from config
+ */
+import chalk from "chalk";
+import ora from "ora";
+import { CONFIG_FILE, loadConfig, setConfigValue } from "../config.js";
+import { pingAuth } from "../api.js";
+import { getApiKey } from "../config.js";
+import { printError, printSuccess, printInfo } from "../output.js";
+export function registerAuthCommand(program) {
+    const auth = program
+        .command("auth")
+        .description("Manage API key authentication");
+    // ── set-key ──────────────────────────────────────────────────────────────────
+    auth
+        .command("set-key [apiKey]")
+        .description("Save your CareerVivid API key to ~/.careervividrc.json")
+        .option("--json", "Machine-readable output")
+        .action(async (apiKeyArg, opts) => {
+        const jsonMode = !!opts.json;
+        let apiKey = apiKeyArg;
+        if (!apiKey) {
+            // Interactive prompt
+            if (jsonMode) {
+                printError("In --json mode, provide the API key as an argument: cv auth set-key <key>", undefined, true);
+                process.exit(1);
+            }
+            console.log();
+            console.log(`  ${chalk.bold("Get your API key at:")} ${chalk.cyan("https://careervivid.app/#/developer")}`);
+            console.log();
+            const { prompt } = await import("enquirer");
+            const answers = await prompt({
+                type: "password",
+                name: "key",
+                message: "Paste your API key",
+            });
+            apiKey = answers.key.trim();
+        }
+        if (!apiKey || !apiKey.startsWith("cv_live_")) {
+            printError("Invalid key format. CareerVivid API keys start with cv_live_", undefined, jsonMode);
+            process.exit(1);
+        }
+        setConfigValue("apiKey", apiKey);
+        if (!jsonMode) {
+            console.log();
+            console.log(`  ${chalk.green("✔")}  Key saved to ${chalk.dim(CONFIG_FILE)}`);
+            console.log(`  ${chalk.dim("Run")} ${chalk.cyan("cv auth check")} ${chalk.dim("to verify it works.")}`);
+            console.log();
+        }
+        else {
+            console.log(JSON.stringify({ success: true, configFile: CONFIG_FILE }));
+        }
+    });
+    // ── check ─────────────────────────────────────────────────────────────────────
+    auth
+        .command("check")
+        .description("Verify your API key is valid")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        const jsonMode = !!opts.json;
+        const key = getApiKey();
+        if (!key) {
+            printError("No API key configured. Run: cv auth set-key", undefined, jsonMode);
+            process.exit(1);
+        }
+        const spinner = jsonMode ? null : ora("Checking API key...").start();
+        const result = await pingAuth();
+        spinner?.stop();
+        if (result.ok) {
+            printSuccess({ status: "Valid", key: `${key.slice(0, 16)}...` }, jsonMode);
+        }
+        else {
+            printError(result.error || "Key check failed", undefined, jsonMode);
+            process.exit(1);
+        }
+    });
+    // ── whoami ────────────────────────────────────────────────────────────────────
+    auth
+        .command("whoami")
+        .description("Print the current API key configuration")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        const jsonMode = !!opts.json;
+        const config = loadConfig();
+        const keyFromEnv = !!process.env.CV_API_KEY;
+        const key = getApiKey();
+        if (!key) {
+            printError("No API key configured. Run: cv auth set-key", undefined, jsonMode);
+            process.exit(1);
+        }
+        const masked = `${key.slice(0, 16)}${"•".repeat(Math.max(0, key.length - 16))}`;
+        printSuccess({
+            "API Key": masked,
+            "Key Source": keyFromEnv ? "Environment (CV_API_KEY)" : `Config file (${CONFIG_FILE})`,
+            "API URL": config.apiUrl || "https://careervivid.app/api/publish (default)",
+        }, jsonMode);
+    });
+    // ── revoke ────────────────────────────────────────────────────────────────────
+    auth
+        .command("revoke")
+        .description("Remove the saved API key from ~/.careervividrc.json")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        const jsonMode = !!opts.json;
+        const config = loadConfig();
+        if (!config.apiKey) {
+            printInfo("No API key in config file to remove.", jsonMode);
+            return;
+        }
+        delete config.apiKey;
+        const { saveConfig } = await import("../config.js");
+        saveConfig(config);
+        if (jsonMode) {
+            console.log(JSON.stringify({ success: true }));
+        }
+        else {
+            console.log();
+            console.log(`  ${chalk.green("✔")}  API key removed from ${chalk.dim(CONFIG_FILE)}`);
+            console.log();
+        }
+    });
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * cv config — view and modify CLI configuration
+ *
+ * Subcommands:
+ *   cv config show              Print entire configuration
+ *   cv config get <key>         Print single config value
+ *   cv config set <key> <val>   Set a config value
+ */
+import { Command } from "commander";
+export declare function registerConfigCommand(program: Command): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/commands/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoG5D"}

package/dist/commands/config.js

@@ -0,0 +1,97 @@
+/**
+ * cv config — view and modify CLI configuration
+ *
+ * Subcommands:
+ *   cv config show              Print entire configuration
+ *   cv config get <key>         Print single config value
+ *   cv config set <key> <val>   Set a config value
+ */
+import chalk from "chalk";
+import { CONFIG_FILE, loadConfig, setConfigValue } from "../config.js";
+import { printError, printSuccess } from "../output.js";
+const VALID_KEYS = ["apiKey", "apiUrl"];
+export function registerConfigCommand(program) {
+    const config = program
+        .command("config")
+        .description("View and modify CLI configuration (~/.careervividrc.json)");
+    // ── show ──────────────────────────────────────────────────────────────────────
+    config
+        .command("show")
+        .description("Print current configuration")
+        .option("--json", "Machine-readable output")
+        .action((opts) => {
+        const jsonMode = !!opts.json;
+        const cfg = loadConfig();
+        if (jsonMode) {
+            // Never leak the full key in JSON — mask it
+            const masked = { ...cfg };
+            if (masked.apiKey)
+                masked.apiKey = `${masked.apiKey.slice(0, 16)}...`;
+            console.log(JSON.stringify({ configFile: CONFIG_FILE, config: masked }));
+            return;
+        }
+        console.log();
+        console.log(`  ${chalk.bold("Config file:")} ${chalk.dim(CONFIG_FILE)}`);
+        console.log();
+        if (!cfg.apiKey && !cfg.apiUrl) {
+            console.log(`  ${chalk.dim("No configuration set. Run: cv auth set-key")}`);
+            console.log();
+            return;
+        }
+        if (cfg.apiKey) {
+            const masked = `${cfg.apiKey.slice(0, 16)}${"•".repeat(cfg.apiKey.length - 16)}`;
+            console.log(`  ${chalk.dim("apiKey".padEnd(10))}  ${masked}`);
+        }
+        if (cfg.apiUrl) {
+            console.log(`  ${chalk.dim("apiUrl".padEnd(10))}  ${cfg.apiUrl}`);
+        }
+        console.log();
+    });
+    // ── get ───────────────────────────────────────────────────────────────────────
+    config
+        .command("get <key>")
+        .description(`Get a config value (keys: ${VALID_KEYS.join(", ")})`)
+        .option("--json", "Machine-readable output")
+        .action((key, opts) => {
+        const jsonMode = !!opts.json;
+        if (!VALID_KEYS.includes(key)) {
+            printError(`Unknown key "${key}". Valid keys: ${VALID_KEYS.join(", ")}`, undefined, jsonMode);
+            process.exit(1);
+        }
+        const cfg = loadConfig();
+        const value = cfg[key];
+        if (!value) {
+            if (jsonMode) {
+                console.log(JSON.stringify({ key, value: null }));
+            }
+            else {
+                console.log(`  ${chalk.dim(key)} is not set`);
+            }
+            return;
+        }
+        // Mask apiKey
+        const displayValue = key === "apiKey"
+            ? `${value.slice(0, 16)}${"•".repeat(value.length - 16)}`
+            : value;
+        if (jsonMode) {
+            console.log(JSON.stringify({ key, value: displayValue }));
+        }
+        else {
+            console.log(`  ${chalk.dim(key.padEnd(10))}  ${displayValue}`);
+        }
+    });
+    // ── set ───────────────────────────────────────────────────────────────────────
+    config
+        .command("set <key> <value>")
+        .description(`Set a config value (keys: ${VALID_KEYS.join(", ")})`)
+        .option("--json", "Machine-readable output")
+        .action((key, value, opts) => {
+        const jsonMode = !!opts.json;
+        if (!VALID_KEYS.includes(key)) {
+            printError(`Unknown key "${key}". Valid keys: ${VALID_KEYS.join(", ")}`, undefined, jsonMode);
+            process.exit(1);
+        }
+        setConfigValue(key, value);
+        printSuccess({ key, saved: "true", configFile: CONFIG_FILE }, jsonMode);
+    });
+}

package/dist/commands/publish.d.ts

@@ -0,0 +1,14 @@
+/**
+ * cv publish — publish content to CareerVivid
+ *
+ * Usage:
+ *   cv publish <file>                     Publish a file
+ *   cv publish -                          Read from stdin
+ *   cv publish README.md --title "..."    Override title
+ *   cv publish arch.mmd --type whiteboard --format mermaid
+ *   cv publish - --dry-run < article.md  Validate without publishing
+ *   cv publish - --json < article.md     Agent-friendly JSON output
+ */
+import { Command } from "commander";
+export declare function registerPublishCommand(program: Command): void;
+//# sourceMappingURL=publish.d.ts.map

package/dist/commands/publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../src/commands/publish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BpC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoJ7D"}

package/dist/commands/publish.js

@@ -0,0 +1,136 @@
+/**
+ * cv publish — publish content to CareerVivid
+ *
+ * Usage:
+ *   cv publish <file>                     Publish a file
+ *   cv publish -                          Read from stdin
+ *   cv publish README.md --title "..."    Override title
+ *   cv publish arch.mmd --type whiteboard --format mermaid
+ *   cv publish - --dry-run < article.md  Validate without publishing
+ *   cv publish - --json < article.md     Agent-friendly JSON output
+ */
+import { readFileSync } from "fs";
+import { extname } from "path";
+import chalk from "chalk";
+import ora from "ora";
+import { publishPost, isApiError } from "../api.js";
+import { printError, printSuccess, handleApiError } from "../output.js";
+function inferFormat(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    if ([".mmd", ".mermaid"].includes(ext))
+        return "mermaid";
+    return "markdown";
+}
+function inferType(format) {
+    return format === "mermaid" ? "whiteboard" : "article";
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+export function registerPublishCommand(program) {
+    program
+        .command("publish [file]")
+        .description([
+        "Publish a markdown or mermaid file to CareerVivid",
+        "",
+        "  cv publish article.md",
+        "  cv publish diagram.mmd --type whiteboard",
+        "  cat article.md | cv publish - --title \"My Article\" --json",
+    ].join("\n"))
+        .option("-t, --title <title>", "Post title (inferred from first heading if omitted)")
+        .option("--type <type>", "Post type: article | whiteboard (default: inferred from format)")
+        .option("--format <format>", "Content format: markdown | mermaid (default: inferred from file extension)")
+        .option("--tags <tags>", "Comma-separated tags, e.g. typescript,firebase,react")
+        .option("--cover <url>", "URL to a cover image")
+        .option("--dry-run", "Validate payload without publishing")
+        .option("--json", "Machine-readable JSON output")
+        .action(async (fileArg, opts) => {
+        const jsonMode = !!opts.json;
+        const dryRun = !!opts.dryRun;
+        // ── Read content ────────────────────────────────────────────────────────
+        let content;
+        let filePath;
+        if (!fileArg || fileArg === "-") {
+            if (!jsonMode) {
+                console.log(`  ${chalk.dim("Reading from stdin... (Ctrl+D to finish)")}`);
+            }
+            content = await readStdin();
+            filePath = "stdin";
+        }
+        else {
+            try {
+                content = readFileSync(fileArg, "utf-8");
+                filePath = fileArg;
+            }
+            catch (err) {
+                printError(`Cannot read file: ${err.message}`, undefined, jsonMode);
+                process.exit(1);
+            }
+        }
+        if (!content.trim()) {
+            printError("Content is empty.", undefined, jsonMode);
+            process.exit(1);
+        }
+        // ── Infer format and type ───────────────────────────────────────────────
+        const format = opts.format ||
+            (filePath !== "stdin" ? inferFormat(filePath) : "markdown");
+        const type = opts.type || inferType(format);
+        // ── Infer title from first heading if not provided ─────────────────────
+        let title = opts.title;
+        if (!title && format === "markdown") {
+            const firstHeading = content.match(/^#\s+(.+)$/m);
+            if (firstHeading) {
+                title = firstHeading[1].trim();
+            }
+        }
+        if (!title) {
+            if (jsonMode) {
+                printError("Title is required. Use --title <title> or add a # heading in your markdown.", undefined, true);
+                process.exit(1);
+            }
+            // Interactive prompt fallback
+            const { prompt } = await import("enquirer");
+            const answers = await prompt({
+                type: "input",
+                name: "title",
+                message: "Post title",
+            });
+            title = answers.title.trim();
+        }
+        // ── Build payload ──────────────────────────────────────────────────────
+        const tags = opts.tags
+            ? opts.tags.split(",").map((t) => t.trim()).filter(Boolean)
+            : [];
+        if (tags.length > 5) {
+            printError("Maximum 5 tags allowed.", undefined, jsonMode);
+            process.exit(1);
+        }
+        const payload = {
+            type,
+            dataFormat: format,
+            title,
+            content,
+            tags,
+            ...(opts.cover ? { coverImage: opts.cover } : {}),
+        };
+        // ── Publish ────────────────────────────────────────────────────────────
+        const spinner = jsonMode || dryRun
+            ? null
+            : ora(`${dryRun ? "Validating" : "Publishing"} ${type}...`).start();
+        const result = await publishPost(payload, dryRun);
+        spinner?.stop();
+        if (isApiError(result)) {
+            handleApiError(result, jsonMode);
+        }
+        printSuccess({
+            Title: title,
+            URL: result.url,
+            "Post ID": result.postId,
+            ...(dryRun ? { Note: "Dry run — not published" } : {}),
+        }, jsonMode);
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Config Manager — reads/writes ~/.careervividrc.json
+ *
+ * Stored fields:
+ *   apiKey   — cv_live_... key
+ *   apiUrl   — override for the publish endpoint (default: prod)
+ */
+export declare const CONFIG_FILE: string;
+export declare const DEFAULT_API_URL = "https://careervivid.app/api/publish";
+export interface CareerVividConfig {
+    apiKey?: string;
+    apiUrl?: string;
+}
+export declare function loadConfig(): CareerVividConfig;
+export declare function saveConfig(config: CareerVividConfig): void;
+export declare function getApiKey(): string | undefined;
+export declare function getApiUrl(): string;
+export declare function setConfigValue(key: keyof CareerVividConfig, value: string): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,eAAO,MAAM,WAAW,QAAyC,CAAC;AAElE,eAAO,MAAM,eAAe,wCAAwC,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,UAAU,IAAI,iBAAiB,CAQ9C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAE1D;AAED,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAG9C;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIhF"}

package/dist/config.js

@@ -0,0 +1,38 @@
+/**
+ * Config Manager — reads/writes ~/.careervividrc.json
+ *
+ * Stored fields:
+ *   apiKey   — cv_live_... key
+ *   apiUrl   — override for the publish endpoint (default: prod)
+ */
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+export const CONFIG_FILE = join(homedir(), ".careervividrc.json");
+export const DEFAULT_API_URL = "https://careervivid.app/api/publish";
+export function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return {};
+    try {
+        const raw = readFileSync(CONFIG_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(config) {
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+export function getApiKey() {
+    // Priority: env var > config file
+    return process.env.CV_API_KEY || loadConfig().apiKey;
+}
+export function getApiUrl() {
+    return process.env.CV_API_URL || loadConfig().apiUrl || DEFAULT_API_URL;
+}
+export function setConfigValue(key, value) {
+    const current = loadConfig();
+    current[key] = value;
+    saveConfig(current);
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * CareerVivid CLI — Entry Point
+ *
+ * Usage:
+ *   cv publish <file>                 Publish a markdown/mermaid file
+ *   cv publish -                      Read from stdin (pipe-friendly)
+ *   cv auth set-key                   Save your API key
+ *   cv auth check                     Test that your API key is valid
+ *   cv config show                    Print current configuration
+ *   cv config set <key> <value>       Update a config value
+ *   cv config get <key>               Print a config value
+ *   cv --help / cv --version
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * CareerVivid CLI — Entry Point
+ *
+ * Usage:
+ *   cv publish <file>                 Publish a markdown/mermaid file
+ *   cv publish -                      Read from stdin (pipe-friendly)
+ *   cv auth set-key                   Save your API key
+ *   cv auth check                     Test that your API key is valid
+ *   cv config show                    Print current configuration
+ *   cv config set <key> <value>       Update a config value
+ *   cv config get <key>               Print a config value
+ *   cv --help / cv --version
+ */
+import { Command } from "commander";
+import { registerAuthCommand } from "./commands/auth.js";
+import { registerPublishCommand } from "./commands/publish.js";
+import { registerConfigCommand } from "./commands/config.js";
+const program = new Command();
+program
+    .name("cv")
+    .description("CareerVivid CLI — publish articles, diagrams, and portfolio updates from your terminal or AI agent")
+    .version("1.0.0", "-v, --version", "Print CLI version")
+    .helpOption("-h, --help", "Show help");
+registerAuthCommand(program);
+registerPublishCommand(program);
+registerConfigCommand(program);
+program.parseAsync(process.argv).catch((err) => {
+    console.error(`\nFatal error: ${err.message}`);
+    process.exit(1);
+});

package/dist/output.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Output helpers — pretty-print (human) vs --json (machine) modes.
+ *
+ * Every command receives an `opts.json` flag. Pass it through to these helpers
+ * to ensure consistent behaviour across human and agent callers.
+ */
+import type { ApiError } from "./api.js";
+export declare function printSuccess(fields: Record<string, string>, jsonMode: boolean): void;
+export declare function printError(message: string, fields?: {
+    field: string;
+    message: string;
+}[], jsonMode?: boolean): void;
+export declare function printInfo(message: string, jsonMode: boolean): void;
+export declare function printTable(rows: Record<string, string>[], jsonMode: boolean): void;
+export declare function handleApiError(err: ApiError, jsonMode: boolean): never;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAIzC,wBAAgB,YAAY,CACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,OAAO,GAClB,IAAI,CAaN;AAED,wBAAgB,UAAU,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,EAC7C,QAAQ,UAAQ,GACjB,IAAI,CAeN;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAIlE;AAED,wBAAgB,UAAU,CACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAC9B,QAAQ,EAAE,OAAO,GAClB,IAAI,CAWN;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAG,KAAK,CAGtE"}

package/dist/output.js

@@ -0,0 +1,57 @@
+/**
+ * Output helpers — pretty-print (human) vs --json (machine) modes.
+ *
+ * Every command receives an `opts.json` flag. Pass it through to these helpers
+ * to ensure consistent behaviour across human and agent callers.
+ */
+import chalk from "chalk";
+// ── Output helpers ─────────────────────────────────────────────────────────────
+export function printSuccess(fields, jsonMode) {
+    if (jsonMode) {
+        console.log(JSON.stringify({ success: true, ...fields }));
+        return;
+    }
+    console.log();
+    console.log(`  ${chalk.green("✔")}  ${chalk.bold("Success!")}`);
+    console.log();
+    for (const [label, value] of Object.entries(fields)) {
+        console.log(`  ${chalk.dim(label.padEnd(10))}  ${chalk.cyan(value)}`);
+    }
+    console.log();
+}
+export function printError(message, fields, jsonMode = false) {
+    if (jsonMode) {
+        console.error(JSON.stringify({ success: false, error: message, fields }));
+        return;
+    }
+    console.error();
+    console.error(`  ${chalk.red("✖")}  ${chalk.bold("Error:")} ${message}`);
+    if (fields && fields.length > 0) {
+        console.error();
+        for (const f of fields) {
+            console.error(`     ${chalk.yellow("•")} ${chalk.bold(f.field)}: ${f.message}`);
+        }
+    }
+    console.error();
+}
+export function printInfo(message, jsonMode) {
+    if (!jsonMode) {
+        console.log(`  ${chalk.blue("ℹ")}  ${message}`);
+    }
+}
+export function printTable(rows, jsonMode) {
+    if (jsonMode) {
+        console.log(JSON.stringify(rows));
+        return;
+    }
+    for (const row of rows) {
+        for (const [k, v] of Object.entries(row)) {
+            console.log(`  ${chalk.dim(k.padEnd(12))}  ${v}`);
+        }
+        console.log();
+    }
+}
+export function handleApiError(err, jsonMode) {
+    printError(err.message, err.fields, jsonMode);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "careervivid",
+  "version": "1.0.0",
+  "description": "Official CLI for CareerVivid — publish articles, diagrams, and portfolio updates from your terminal or AI agent",
+  "type": "module",
+  "bin": {
+    "cv": "dist/index.js",
+    "careervivid": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "enquirer": "^2.4.1",
+    "ora": "^8.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "careervivid",
+    "cli",
+    "developer-tools",
+    "publish",
+    "portfolio",
+    "ai-agent",
+    "mcp"
+  ],
+  "author": "CareerVivid",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jastalk/CareerVivid.git",
+    "directory": "cli"
+  },
+  "homepage": "https://careervivid.app",
+  "bugs": {
+    "url": "https://github.com/Jastalk/CareerVivid/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}