@duvoai/cli 0.0.1

package/dist/config/profiles.js

@@ -0,0 +1,78 @@
+const PROFILE_NAME_PATTERN = /^[a-z0-9._-]+$/;
+const MAX_PROFILE_NAME_LENGTH = 40;
+export function isValidProfileName(name) {
+    if (name.length === 0 || name.length > MAX_PROFILE_NAME_LENGTH) {
+        return false;
+    }
+    return PROFILE_NAME_PATTERN.test(name);
+}
+export function assertValidProfileName(name) {
+    if (!isValidProfileName(name)) {
+        throw new Error(`Invalid profile name "${name}". Use lowercase letters, digits, ` +
+            `".", "-" or "_", max ${MAX_PROFILE_NAME_LENGTH} chars.`);
+    }
+}
+/**
+ * Add (or replace) a profile. The first profile added becomes the
+ * default automatically. Returns the updated config without mutating
+ * the input.
+ */
+export function addProfile(config, name, profile) {
+    assertValidProfileName(name);
+    const profiles = { ...config.profiles, [name]: profile };
+    const defaultProfile = config.defaultProfile === null ? name : config.defaultProfile;
+    return { defaultProfile, profiles };
+}
+/**
+ * Remove a profile. If the removed profile was the default, picks
+ * another profile alphabetically as the new default, or clears it if
+ * none remain.
+ */
+export function removeProfile(config, name) {
+    if (!(name in config.profiles)) {
+        return config;
+    }
+    const profiles = { ...config.profiles };
+    delete profiles[name];
+    if (config.defaultProfile !== name) {
+        return { defaultProfile: config.defaultProfile, profiles };
+    }
+    const remaining = Object.keys(profiles).sort();
+    const defaultProfile = remaining.length > 0 ? remaining[0] : null;
+    return { defaultProfile, profiles };
+}
+export function renameProfile(config, oldName, newName) {
+    if (!(oldName in config.profiles)) {
+        throw new Error(`Profile "${oldName}" does not exist.`);
+    }
+    if (oldName === newName) {
+        return config;
+    }
+    assertValidProfileName(newName);
+    if (newName in config.profiles) {
+        throw new Error(`Profile "${newName}" already exists.`);
+    }
+    const profiles = { ...config.profiles };
+    profiles[newName] = profiles[oldName];
+    delete profiles[oldName];
+    const defaultProfile = config.defaultProfile === oldName ? newName : config.defaultProfile;
+    return { defaultProfile, profiles };
+}
+export function setDefaultProfile(config, name) {
+    if (!(name in config.profiles)) {
+        throw new Error(`Profile "${name}" does not exist.`);
+    }
+    return { ...config, defaultProfile: name };
+}
+export function listProfiles(config) {
+    return Object.entries(config.profiles)
+        .map(([name, profile]) => {
+        return {
+            name,
+            apiKey: profile.apiKey,
+            apiBaseUrl: profile.apiBaseUrl,
+            isDefault: config.defaultProfile === name,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/config/resolve.d.ts

@@ -0,0 +1,29 @@
+import { type CliEnv } from "../config/env.js";
+import { type Config } from "../config/types.js";
+import { AuthCliError } from "../errors.js";
+export type ResolvedConfig = {
+    apiKey: string | null;
+    apiBaseUrl: string;
+    /** Name of the profile we resolved to, or null if we fell through to env-only. */
+    profileName: string | null;
+};
+export type ResolveOptions = {
+    /** From the --profile CLI flag. Takes precedence over env and stored default. */
+    profileFlag?: string | undefined;
+};
+/**
+ * Selection precedence:
+ *   profile: --profile flag > DUVO_PROFILE env > config.defaultProfile
+ *   apiKey:  DUVO_API_KEY env > profile.apiKey
+ *   baseUrl: DUVO_API_BASE_URL env > profile.apiBaseUrl > default
+ *
+ * If --profile is given but unknown, this throws (caller maps to exit 2).
+ * DUVO_PROFILE being unset/unknown falls through silently so users can use
+ * env overrides without breaking other shells.
+ */
+export declare function resolveConfig(options?: ResolveOptions): Promise<ResolvedConfig>;
+export declare function selectEffectiveConfig(config: Config, options: ResolveOptions, env: CliEnv): ResolvedConfig;
+export declare class UnknownProfileError extends AuthCliError {
+    readonly profileName: string;
+    constructor(profileName: string);
+}

package/dist/config/resolve.js

@@ -0,0 +1,46 @@
+import { DEFAULT_API_BASE_URL } from "../config/defaults.js";
+import { parseCliEnv } from "../config/env.js";
+import { readConfig } from "../config/store.js";
+import { AuthCliError } from "../errors.js";
+/**
+ * Selection precedence:
+ *   profile: --profile flag > DUVO_PROFILE env > config.defaultProfile
+ *   apiKey:  DUVO_API_KEY env > profile.apiKey
+ *   baseUrl: DUVO_API_BASE_URL env > profile.apiBaseUrl > default
+ *
+ * If --profile is given but unknown, this throws (caller maps to exit 2).
+ * DUVO_PROFILE being unset/unknown falls through silently so users can use
+ * env overrides without breaking other shells.
+ */
+export async function resolveConfig(options = {}) {
+    const config = await readConfig();
+    return selectEffectiveConfig(config, options, parseCliEnv(process.env));
+}
+export function selectEffectiveConfig(config, options, env) {
+    const profileName = selectProfileName(config, options, env);
+    const profile = profileName ? (config.profiles[profileName] ?? null) : null;
+    const apiKey = env.DUVO_API_KEY ?? profile?.apiKey ?? null;
+    const apiBaseUrl = env.DUVO_API_BASE_URL ?? profile?.apiBaseUrl ?? DEFAULT_API_BASE_URL;
+    return { apiKey, apiBaseUrl, profileName };
+}
+function selectProfileName(config, options, env) {
+    const flag = options.profileFlag;
+    if (flag && flag.length > 0) {
+        if (!(flag in config.profiles)) {
+            throw new UnknownProfileError(flag);
+        }
+        return flag;
+    }
+    if (env.DUVO_PROFILE && env.DUVO_PROFILE in config.profiles) {
+        return env.DUVO_PROFILE;
+    }
+    return config.defaultProfile;
+}
+export class UnknownProfileError extends AuthCliError {
+    profileName;
+    constructor(profileName) {
+        super(`Profile "${profileName}" does not exist. Run \`duvo profiles list\` to see available profiles.`);
+        this.profileName = profileName;
+        this.name = "UnknownProfileError";
+    }
+}

package/dist/config/store.d.ts

@@ -0,0 +1,4 @@
+import { type Config } from "../config/types.js";
+export declare function readConfig(): Promise<Config>;
+export declare function writeConfig(config: Config): Promise<void>;
+export declare function deleteConfig(): Promise<boolean>;

package/dist/config/store.js

@@ -0,0 +1,94 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { DEFAULT_API_BASE_URL, emptyConfig } from "../config/defaults.js";
+import { getConfigPath } from "../config/paths.js";
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+export async function readConfig() {
+    const path = getConfigPath();
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        return normalizeConfig(parsed);
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return emptyConfig();
+        }
+        throw error;
+    }
+}
+export async function writeConfig(config) {
+    const path = getConfigPath();
+    await mkdir(dirname(path), { recursive: true, mode: DIR_MODE });
+    await writeFile(path, JSON.stringify(config, null, 2), {
+        mode: FILE_MODE,
+        encoding: "utf8",
+    });
+}
+export async function deleteConfig() {
+    const path = getConfigPath();
+    try {
+        await rm(path);
+        return true;
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Accepts the legacy single-profile shape ({ apiKey, apiBaseUrl }) and
+ * migrates it into the named-profile shape under the "default" name. Any
+ * fields we don't recognize are dropped.
+ */
+function normalizeConfig(parsed) {
+    if (parsed === null || typeof parsed !== "object") {
+        return emptyConfig();
+    }
+    const record = parsed;
+    // Legacy single-profile migration.
+    if (typeof record.apiKey === "string" &&
+        record.profiles === undefined &&
+        record.defaultProfile === undefined) {
+        const apiBaseUrl = typeof record.apiBaseUrl === "string"
+            ? record.apiBaseUrl
+            : DEFAULT_API_BASE_URL;
+        return {
+            defaultProfile: "default",
+            profiles: {
+                default: { apiKey: record.apiKey, apiBaseUrl },
+            },
+        };
+    }
+    const profiles = {};
+    const rawProfiles = record.profiles && typeof record.profiles === "object"
+        ? record.profiles
+        : {};
+    for (const [name, value] of Object.entries(rawProfiles)) {
+        if (value === null || typeof value !== "object") {
+            continue;
+        }
+        const profile = value;
+        if (typeof profile.apiKey !== "string") {
+            continue;
+        }
+        const apiBaseUrl = typeof profile.apiBaseUrl === "string"
+            ? profile.apiBaseUrl
+            : DEFAULT_API_BASE_URL;
+        profiles[name] = { apiKey: profile.apiKey, apiBaseUrl };
+    }
+    const defaultProfile = typeof record.defaultProfile === "string" &&
+        record.defaultProfile in profiles
+        ? record.defaultProfile
+        : null;
+    return { defaultProfile, profiles };
+}
+function isNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/config/types.d.ts

@@ -0,0 +1,8 @@
+export type Profile = {
+    apiKey: string;
+    apiBaseUrl: string;
+};
+export type Config = {
+    defaultProfile: string | null;
+    profiles: Record<string, Profile>;
+};

package/dist/config/types.js

@@ -0,0 +1 @@
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+export declare const EXIT_CODE: {
+    readonly SUCCESS: 0;
+    readonly GENERIC: 1;
+    readonly AUTH: 2;
+    readonly NOT_FOUND: 3;
+};
+export type ExitCode = (typeof EXIT_CODE)[keyof typeof EXIT_CODE];
+export declare class CliError extends Error {
+    readonly exitCode: ExitCode;
+    constructor(message: string, exitCode?: ExitCode);
+}
+export declare class AuthCliError extends CliError {
+    constructor(message: string);
+}
+export declare class NotFoundCliError extends CliError {
+    constructor(message: string);
+}
+/** Signals a cooperative user-driven cancel (Ctrl-C, answering "no"). */
+export declare class CancelCliError extends CliError {
+    constructor(message?: string);
+}
+export declare function handleCliError(error: unknown): never;

package/dist/errors.js

@@ -0,0 +1,42 @@
+export const EXIT_CODE = {
+    SUCCESS: 0,
+    GENERIC: 1,
+    AUTH: 2,
+    NOT_FOUND: 3,
+};
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT_CODE.GENERIC) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}
+export class AuthCliError extends CliError {
+    constructor(message) {
+        super(message, EXIT_CODE.AUTH);
+        this.name = "AuthCliError";
+    }
+}
+export class NotFoundCliError extends CliError {
+    constructor(message) {
+        super(message, EXIT_CODE.NOT_FOUND);
+        this.name = "NotFoundCliError";
+    }
+}
+/** Signals a cooperative user-driven cancel (Ctrl-C, answering "no"). */
+export class CancelCliError extends CliError {
+    constructor(message = "Cancelled.") {
+        super(message, EXIT_CODE.GENERIC);
+        this.name = "CancelCliError";
+    }
+}
+export function handleCliError(error) {
+    if (error instanceof CliError) {
+        process.stderr.write(`${error.message}\n`);
+        process.exit(error.exitCode);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`error: ${message}\n`);
+    process.exit(EXIT_CODE.GENERIC);
+}

package/dist/output/format.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Mask the secret portion of an API key, leaving the non-secret prefix
+ * visible so users can distinguish keys in listings.
+ *
+ * Keys have the shape `dv_<prefix>-<secret>`. Everything up to and
+ * including the first `-` is the public id; everything after is masked.
+ * Keys without a dash (shouldn't happen in practice) fall back to a
+ * fixed-length prefix so we never leak the tail regardless of format.
+ */
+export declare function truncateApiKey(key: string): string;
+export declare function padRight(value: string, width: number): string;

package/dist/output/format.js

@@ -0,0 +1,26 @@
+const FALLBACK_PREFIX_LEN = 11;
+/**
+ * Mask the secret portion of an API key, leaving the non-secret prefix
+ * visible so users can distinguish keys in listings.
+ *
+ * Keys have the shape `dv_<prefix>-<secret>`. Everything up to and
+ * including the first `-` is the public id; everything after is masked.
+ * Keys without a dash (shouldn't happen in practice) fall back to a
+ * fixed-length prefix so we never leak the tail regardless of format.
+ */
+export function truncateApiKey(key) {
+    const dashIdx = key.indexOf("-");
+    const visibleLen = dashIdx >= 0 ? dashIdx + 1 : FALLBACK_PREFIX_LEN;
+    if (key.length <= visibleLen) {
+        return key;
+    }
+    const visible = key.slice(0, visibleLen);
+    const masked = "*".repeat(key.length - visibleLen);
+    return `${visible}${masked}`;
+}
+export function padRight(value, width) {
+    if (value.length >= width) {
+        return value;
+    }
+    return value + " ".repeat(width - value.length);
+}

package/dist/output/json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Prints a value as pretty JSON (2-space indent) to stdout. This is the
+ * stable output contract — scripts should always be able to `| jq` the
+ * result. No colour, no truncation.
+ */
+export declare function printJson(data: unknown): void;

package/dist/output/json.js

@@ -0,0 +1,8 @@
+/**
+ * Prints a value as pretty JSON (2-space indent) to stdout. This is the
+ * stable output contract — scripts should always be able to `| jq` the
+ * result. No colour, no truncation.
+ */
+export function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}

package/dist/output/table.d.ts

@@ -0,0 +1,16 @@
+export type Column<T> = {
+    header: string;
+    cell: (row: T) => string;
+    /**
+     * Optional cap on the rendered width of the column. Cells wider than
+     * this are truncated with a trailing `…` to keep each row on one line.
+     * The header is truncated too so the column never exceeds the cap.
+     */
+    maxWidth?: number;
+};
+/**
+ * Renders a fixed-width ASCII table. Columns auto-size to the widest
+ * cell (including the header) but never exceed `maxWidth` when set.
+ * No colour — non-TTY safe by default.
+ */
+export declare function renderTable<T>(columns: readonly Column<T>[], rows: readonly T[]): string;

package/dist/output/table.js

@@ -0,0 +1,35 @@
+/**
+ * Renders a fixed-width ASCII table. Columns auto-size to the widest
+ * cell (including the header) but never exceed `maxWidth` when set.
+ * No colour — non-TTY safe by default.
+ */
+export function renderTable(columns, rows) {
+    if (columns.length === 0) {
+        return "";
+    }
+    const cells = rows.map((row) => columns.map((col) => col.cell(row)));
+    const widths = columns.map((col, i) => {
+        const contentWidth = Math.max(col.header.length, ...cells.map((row) => row[i].length));
+        return col.maxWidth ? Math.min(col.maxWidth, contentWidth) : contentWidth;
+    });
+    const headerLine = columns
+        .map((col, i) => pad(truncate(col.header, widths[i]), widths[i]))
+        .join("  ");
+    const bodyLines = cells.map((row) => row.map((cell, i) => pad(truncate(cell, widths[i]), widths[i])).join("  "));
+    return [headerLine, ...bodyLines].join("\n");
+}
+function pad(value, width) {
+    if (value.length >= width) {
+        return value;
+    }
+    return value + " ".repeat(width - value.length);
+}
+function truncate(value, width) {
+    if (value.length <= width) {
+        return value;
+    }
+    if (width <= 1) {
+        return "…".slice(0, width);
+    }
+    return `${value.slice(0, width - 1)}…`;
+}

package/dist/output/text.d.ts

@@ -0,0 +1,9 @@
+export type KeyValueEntry = {
+    label: string;
+    value: string;
+};
+/**
+ * Renders a labelled key/value block for single-resource views.
+ * Labels are left-padded to the widest label so values line up.
+ */
+export declare function renderKeyValue(entries: readonly KeyValueEntry[]): string;

package/dist/output/text.js

@@ -0,0 +1,13 @@
+/**
+ * Renders a labelled key/value block for single-resource views.
+ * Labels are left-padded to the widest label so values line up.
+ */
+export function renderKeyValue(entries) {
+    if (entries.length === 0) {
+        return "";
+    }
+    const labelWidth = Math.max(...entries.map((e) => e.label.length));
+    return entries
+        .map((entry) => `${entry.label.padEnd(labelWidth)}  ${entry.value}`)
+        .join("\n");
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@duvoai/cli",
+  "version": "0.0.1",
+  "description": "Command-line interface for the Duvo public API",
+  "type": "module",
+  "main": "dist/bin/duvo.js",
+  "bin": {
+    "duvo": "./dist/bin/duvo.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json && node scripts/make-bin-executable.mjs",
+    "dev": "tsx src/bin/duvo.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "commander": "^12.1.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.20.3",
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.22.0"
+  }
+}