dashform-cli 0.1.0

package/README.md

@@ -0,0 +1,22 @@
+# dashform-cli
+
+Dashform CLI (TypeScript) scaffold for API-key authenticated access to Dashform APIs.
+
+## Commands
+
+- `dashform auth login --api-key <key>`
+- `dashform auth whoami`
+- `dashform auth logout`
+- `dashform forms list`
+- `dashform forms get <id>`
+- `dashform forms create --name <name> [--description <description>] [--type structured|dynamic] [--tone <tone>]`
+- `dashform forms update <id> [--name <name>] [--description <description>] [--type structured|dynamic] [--tone <tone>] [--clear-tone]`
+- `dashform forms delete <id> --yes`
+
+## Development
+
+```bash
+pnpm install
+pnpm check-types
+pnpm dev -- --help
+```

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "dashform-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "dashform": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "cac": "^6.7.14",
+    "picocolors": "^1.1.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "@types/node": "^25.2.2"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { loadConfig } from "./config.js";
+import { requestJson } from "./http/client.js";
+import { type MeResponse } from "./types.js";
+
+const meSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  name: z.string().nullable().optional(),
+  emailVerified: z.boolean(),
+  createdAt: z.string().optional(),
+});
+
+export async function whoAmI() {
+  const config = await loadConfig();
+  return requestJson(config, "/api/v1/me", meSchema) as Promise<MeResponse>;
+}

package/src/cli.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { cac } from "cac";
+import pc from "picocolors";
+import { loadConfig } from "./config.js";
+import { loginCommand } from "./commands/auth/login.js";
+import { logoutCommand } from "./commands/auth/logout.js";
+import { whoamiCommand } from "./commands/auth/whoami.js";
+import { getFormCommand } from "./commands/forms/get.js";
+import { listFormsCommand } from "./commands/forms/list.js";
+import { createFormCommand } from "./commands/forms/create.js";
+import { updateFormCommand } from "./commands/forms/update.js";
+import { deleteFormCommand } from "./commands/forms/delete.js";
+import { describeHttpError } from "./http/errors.js";
+
+const cli = cac("dashform");
+
+cli
+  .command("auth login", "Store a Dashform API key")
+  .option("--api-key <key>", "API key value")
+  .option("--base-url <url>", "Override Dashform base URL")
+  .action(async (options) => {
+    await loginCommand(options);
+    process.stdout.write("Saved API key. Run `dashform auth whoami` to verify.\n");
+  });
+
+cli.command("auth logout", "Remove the stored API key").action(async () => {
+  await logoutCommand();
+  process.stdout.write("Removed API key.\n");
+});
+
+cli
+  .command("auth whoami", "Show the current authenticated user")
+  .option("--json", "Print JSON output")
+  .action(async (options) => {
+    await whoamiCommand(Boolean(options.json));
+  });
+
+cli
+  .command("forms list", "List your forms")
+  .option("--json", "Print JSON output")
+  .action(async (options) => {
+    await listFormsCommand(Boolean(options.json));
+  });
+
+cli
+  .command("forms get <id>", "Get a form by ID or public ID")
+  .option("--json", "Print JSON output")
+  .action(async (id, options) => {
+    await getFormCommand(id, Boolean(options.json));
+  });
+
+cli
+  .command("forms create", "Create a form")
+  .option("--name <name>", "Form name")
+  .option("--description <description>", "Form description")
+  .option("--type <type>", "Form type: structured | dynamic")
+  .option("--tone <tone>", "Form tone")
+  .option("--json", "Print JSON output")
+  .action(async (options) => {
+    await createFormCommand({
+      name: options.name,
+      description: options.description,
+      type: options.type,
+      tone: options.tone,
+      json: Boolean(options.json),
+    });
+  });
+
+cli
+  .command("forms update <id>", "Update a form by ID or public ID")
+  .option("--name <name>", "Update form name")
+  .option("--description <description>", "Update form description")
+  .option("--type <type>", "Update form type: structured | dynamic")
+  .option("--tone <tone>", "Update form tone")
+  .option("--clear-tone", "Clear form tone")
+  .option("--json", "Print JSON output")
+  .action(async (id, options) => {
+    await updateFormCommand(id, {
+      name: options.name,
+      description: options.description,
+      type: options.type,
+      tone: options.tone,
+      clearTone: Boolean(options.clearTone),
+      json: Boolean(options.json),
+    });
+  });
+
+cli
+  .command("forms delete <id>", "Delete a form by ID or public ID")
+  .option("-y, --yes", "Confirm deletion")
+  .option("--json", "Print JSON output")
+  .action(async (id, options) => {
+    await deleteFormCommand(id, {
+      yes: Boolean(options.yes),
+      json: Boolean(options.json),
+    });
+  });
+
+cli.command("config", "Show current config (without API key)").action(async () => {
+  const config = await loadConfig();
+  process.stdout.write(
+    `${JSON.stringify({ ...config, apiKey: config.apiKey ? "***" : null }, null, 2)}\n`
+  );
+});
+
+cli.help();
+cli.version("0.1.0");
+
+cli.parse();
+
+process.on("unhandledRejection", (error) => {
+  process.stderr.write(`${pc.red(describeHttpError(error))}\n`);
+  process.exitCode = 1;
+});

package/src/commands/auth/login.ts

@@ -0,0 +1,28 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { updateConfig } from "../../config.js";
+
+type LoginOptions = {
+  apiKey?: string;
+  baseUrl?: string;
+};
+
+export async function loginCommand(options: LoginOptions) {
+  const rl = createInterface({ input, output });
+  try {
+    const apiKey = options.apiKey ?? (await rl.question("Dashform API key: "));
+    const baseUrl = options.baseUrl;
+
+    if (!apiKey.trim()) {
+      throw new Error("API key is required");
+    }
+
+    await updateConfig((current) => ({
+      ...current,
+      apiKey: apiKey.trim(),
+      baseUrl: baseUrl?.trim() || current.baseUrl,
+    }));
+  } finally {
+    rl.close();
+  }
+}

package/src/commands/auth/logout.ts

@@ -0,0 +1,5 @@
+import { updateConfig } from "../../config.js";
+
+export async function logoutCommand() {
+  await updateConfig((current) => ({ ...current, apiKey: null }));
+}

package/src/commands/auth/whoami.ts

@@ -0,0 +1,8 @@
+import { whoAmI } from "../../auth.js";
+import { loadConfig } from "../../config.js";
+import { printData } from "../../output.js";
+
+export async function whoamiCommand(json?: boolean) {
+  const [me, config] = await Promise.all([whoAmI(), loadConfig()]);
+  printData(me, json ? "json" : config.outputFormat);
+}

package/src/commands/forms/create.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { loadConfig } from "../../config.js";
+import { requestJson } from "../../http/client.js";
+import { printData } from "../../output.js";
+
+const formTypeSchema = z.enum(["structured", "dynamic"]);
+
+const formSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  public_id: z.string(),
+  type: formTypeSchema,
+  created_at: z.string(),
+  updated_at: z.string(),
+  organization_id: z.string().optional(),
+  user_id: z.string().optional(),
+});
+
+export type CreateFormOptions = {
+  name?: string;
+  description?: string;
+  type?: string;
+  tone?: string;
+  json?: boolean;
+};
+
+export async function createFormCommand(options: CreateFormOptions) {
+  const name = options.name?.trim();
+  if (!name) {
+    throw new Error("Missing required option: --name");
+  }
+
+  let type: z.infer<typeof formTypeSchema> | undefined;
+  if (options.type !== undefined) {
+    const parsedType = formTypeSchema.safeParse(options.type);
+    if (!parsedType.success) {
+      throw new Error("Invalid --type. Expected one of: structured, dynamic");
+    }
+    type = parsedType.data;
+  }
+
+  const payload: Record<string, unknown> = { name };
+  if (options.description !== undefined) {
+    payload.description = options.description;
+  }
+  if (options.tone !== undefined) {
+    payload.tone = options.tone;
+  }
+  if (type !== undefined) {
+    payload.type = type;
+  }
+
+  const config = await loadConfig();
+  const form = await requestJson(config, "/api/v1/forms", formSchema, {
+    method: "POST",
+    body: payload,
+  });
+
+  printData(form, options.json ? "json" : config.outputFormat);
+}

package/src/commands/forms/delete.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { loadConfig } from "../../config.js";
+import { requestJson } from "../../http/client.js";
+import { printData } from "../../output.js";
+
+const deleteFormSchema = z.object({
+  deleted: z.boolean(),
+});
+
+export type DeleteFormOptions = {
+  yes?: boolean;
+  json?: boolean;
+};
+
+export async function deleteFormCommand(id: string, options: DeleteFormOptions) {
+  if (!options.yes) {
+    throw new Error("Refusing to delete without confirmation. Re-run with --yes");
+  }
+
+  const config = await loadConfig();
+  const result = await requestJson(
+    config,
+    `/api/v1/forms/${encodeURIComponent(id)}`,
+    deleteFormSchema,
+    {
+      method: "DELETE",
+    }
+  );
+
+  printData(result, options.json ? "json" : config.outputFormat);
+}

package/src/commands/forms/get.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { loadConfig } from "../../config.js";
+import { requestJson } from "../../http/client.js";
+import { printData } from "../../output.js";
+
+const formSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  public_id: z.string(),
+  created_at: z.string(),
+  updated_at: z.string().optional(),
+  organization_id: z.string().optional(),
+  user_id: z.string().optional(),
+});
+
+export async function getFormCommand(id: string, json?: boolean) {
+  const config = await loadConfig();
+  const form = await requestJson(config, `/api/v1/forms/${encodeURIComponent(id)}`, formSchema);
+  printData(form, json ? "json" : config.outputFormat);
+}

package/src/commands/forms/list.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { loadConfig } from "../../config.js";
+import { requestJson } from "../../http/client.js";
+import { printData } from "../../output.js";
+
+const formListItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  public_id: z.string(),
+  created_at: z.string(),
+});
+
+export async function listFormsCommand(json?: boolean) {
+  const config = await loadConfig();
+  const forms = await requestJson(config, "/api/v1/forms", z.array(formListItemSchema));
+  printData(forms, json ? "json" : config.outputFormat);
+}

package/src/commands/forms/update.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { loadConfig } from "../../config.js";
+import { requestJson } from "../../http/client.js";
+import { printData } from "../../output.js";
+
+const formTypeSchema = z.enum(["structured", "dynamic"]);
+
+const formSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  public_id: z.string(),
+  type: formTypeSchema,
+  created_at: z.string(),
+  updated_at: z.string(),
+  organization_id: z.string().optional(),
+  user_id: z.string().optional(),
+});
+
+export type UpdateFormOptions = {
+  name?: string;
+  description?: string;
+  type?: string;
+  tone?: string;
+  clearTone?: boolean;
+  json?: boolean;
+};
+
+export async function updateFormCommand(id: string, options: UpdateFormOptions) {
+  if (options.tone !== undefined && options.clearTone) {
+    throw new Error("Use either --tone or --clear-tone, not both");
+  }
+
+  const payload: Record<string, unknown> = {};
+
+  if (options.name !== undefined) {
+    const name = options.name.trim();
+    if (name.length === 0) {
+      throw new Error("Invalid --name. Must be at least 1 character");
+    }
+    payload.name = name;
+  }
+
+  if (options.description !== undefined) {
+    payload.description = options.description;
+  }
+
+  if (options.type !== undefined) {
+    const parsedType = formTypeSchema.safeParse(options.type);
+    if (!parsedType.success) {
+      throw new Error("Invalid --type. Expected one of: structured, dynamic");
+    }
+    payload.type = parsedType.data;
+  }
+
+  if (options.clearTone) {
+    payload.tone = null;
+  } else if (options.tone !== undefined) {
+    payload.tone = options.tone;
+  }
+
+  if (Object.keys(payload).length === 0) {
+    throw new Error(
+      "No update fields provided. Use one of: --name, --description, --type, --tone, --clear-tone"
+    );
+  }
+
+  const config = await loadConfig();
+  const form = await requestJson(config, `/api/v1/forms/${encodeURIComponent(id)}`, formSchema, {
+    method: "PATCH",
+    body: payload,
+  });
+
+  printData(form, options.json ? "json" : config.outputFormat);
+}

package/src/config.ts

@@ -0,0 +1,68 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { z } from "zod";
+import { type CliConfig } from "./types.js";
+
+const configSchema = z.object({
+  baseUrl: z.string().url(),
+  apiKey: z.string().min(1).nullable(),
+  outputFormat: z.enum(["table", "json"]),
+  timeoutMs: z.number().int().positive(),
+});
+
+const defaultConfig: CliConfig = {
+  baseUrl: "https://getaiform.com",
+  apiKey: null,
+  outputFormat: "table",
+  timeoutMs: 15_000,
+};
+
+export function getConfigPath() {
+  const xdgHome = process.env.XDG_CONFIG_HOME;
+  const base = xdgHome && xdgHome.length > 0 ? xdgHome : join(homedir(), ".config");
+  return join(base, "dashform", "config.json");
+}
+
+export async function loadConfig(): Promise<CliConfig> {
+  const path = getConfigPath();
+
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = configSchema.partial().parse(JSON.parse(raw));
+
+    return {
+      baseUrl: parsed.baseUrl ?? defaultConfig.baseUrl,
+      apiKey: parsed.apiKey ?? defaultConfig.apiKey,
+      outputFormat: parsed.outputFormat ?? defaultConfig.outputFormat,
+      timeoutMs: parsed.timeoutMs ?? defaultConfig.timeoutMs,
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return defaultConfig;
+    }
+
+    if (error instanceof z.ZodError) {
+      throw new Error(`Invalid Dashform config at ${path}`);
+    }
+
+    throw error;
+  }
+}
+
+export async function saveConfig(nextConfig: CliConfig) {
+  const path = getConfigPath();
+  await mkdir(dirname(path), { recursive: true });
+  const validated = configSchema.parse(nextConfig);
+  await writeFile(path, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
+  await chmod(path, 0o600);
+}
+
+export async function updateConfig(
+  updater: (current: CliConfig) => CliConfig | Promise<CliConfig>
+) {
+  const current = await loadConfig();
+  const next = await updater(current);
+  await saveConfig(next);
+  return next;
+}

package/src/http/client.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { type CliConfig } from "../types.js";
+import { HttpError } from "./errors.js";
+
+type RequestOptions = {
+  method?: "GET" | "POST" | "PATCH" | "DELETE";
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: unknown;
+};
+
+function getAuthHeaders(config: CliConfig): Record<string, string> {
+  if (!config.apiKey) {
+    return {};
+  }
+
+  return {
+    "x-api-key": config.apiKey,
+  };
+}
+
+function buildUrl(baseUrl: string, path: string, query?: RequestOptions["query"]) {
+  const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined) {
+        continue;
+      }
+
+      url.searchParams.set(key, String(value));
+    }
+  }
+
+  return url;
+}
+
+export async function requestJson<T>(
+  config: CliConfig,
+  path: string,
+  schema: z.ZodType<T>,
+  options: RequestOptions = {}
+): Promise<T> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+
+  try {
+    const url = buildUrl(config.baseUrl, path, options.query);
+    const init: RequestInit = {
+      method: options.method ?? "GET",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "dashform-cli/dev",
+        ...getAuthHeaders(config),
+      },
+      signal: controller.signal,
+    };
+
+    if (options.body !== undefined) {
+      init.body = JSON.stringify(options.body);
+    }
+
+    const response = await fetch(url, init);
+    const text = await response.text();
+
+    let parsed: unknown = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+
+    if (!response.ok) {
+      const message =
+        (typeof parsed === "object" && parsed && "error_description" in parsed
+          ? (parsed as { error_description?: string }).error_description
+          : undefined) ??
+        (typeof parsed === "object" && parsed && "message" in parsed
+          ? (parsed as { message?: string }).message
+          : undefined) ??
+        `Request failed for ${url.pathname}`;
+
+      throw new HttpError(message, response.status, parsed);
+    }
+
+    return schema.parse(parsed);
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/http/errors.ts

@@ -0,0 +1,22 @@
+export class HttpError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly body: unknown
+  ) {
+    super(message);
+    this.name = "HttpError";
+  }
+}
+
+export function describeHttpError(error: unknown) {
+  if (error instanceof HttpError) {
+    return `${error.message} (HTTP ${error.status})`;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return "Unknown error";
+}

package/src/output.ts

@@ -0,0 +1,62 @@
+import pc from "picocolors";
+import { type OutputFormat } from "./types.js";
+
+export function printData(data: unknown, format: OutputFormat) {
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    return;
+  }
+
+  if (Array.isArray(data)) {
+    printArrayTable(data);
+    return;
+  }
+
+  if (data && typeof data === "object") {
+    for (const [key, value] of Object.entries(data)) {
+      process.stdout.write(`${pc.cyan(key)}: ${String(value ?? "")}\n`);
+    }
+    return;
+  }
+
+  process.stdout.write(`${String(data)}\n`);
+}
+
+function printArrayTable(items: unknown[]) {
+  if (items.length === 0) {
+    process.stdout.write("No results.\n");
+    return;
+  }
+
+  const rows = items.map((item) => {
+    if (!item || typeof item !== "object") {
+      return { value: String(item) };
+    }
+
+    return Object.fromEntries(
+      Object.entries(item).map(([key, value]) => [key, value == null ? "" : String(value)])
+    );
+  });
+
+  const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
+  const widths = new Map(
+    columns.map((column) => [
+      column,
+      Math.max(column.length, ...rows.map((row) => (row[column] ?? "").length)),
+    ])
+  );
+
+  const header = columns
+    .map((column) => pc.bold(column.padEnd(widths.get(column) ?? column.length)))
+    .join("  ");
+  const divider = columns
+    .map((column) => "-".repeat(widths.get(column) ?? column.length))
+    .join("  ");
+
+  process.stdout.write(`${header}\n${divider}\n`);
+  for (const row of rows) {
+    process.stdout.write(
+      `${columns.map((column) => (row[column] ?? "").padEnd(widths.get(column) ?? column.length)).join("  ")}\n`
+    );
+  }
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+export type OutputFormat = "table" | "json";
+
+export type CliConfig = {
+  baseUrl: string;
+  apiKey: string | null;
+  outputFormat: OutputFormat;
+  timeoutMs: number;
+};
+
+export type MeResponse = {
+  id: string;
+  email: string;
+  name: string | null;
+  emailVerified: boolean;
+  createdAt?: string;
+};
+
+export type FormListItem = {
+  id: string;
+  name: string;
+  description: string;
+  public_id: string;
+  created_at: string;
+};
+
+export type FormType = "structured" | "dynamic";
+
+export type FormDetail = FormListItem & {
+  type?: FormType;
+  organization_id?: string;
+  user_id?: string;
+  updated_at?: string;
+};

package/tests/config.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from "vitest";
+
+import { getConfigPath } from "../src/config.js";
+
+describe("config", () => {
+  it("uses an xdg-style config path", () => {
+    expect(getConfigPath()).toContain("dashform/config.json");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2024"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}