@quillmeetings/cli 0.1.0

package/src/config.js

@@ -0,0 +1,132 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function defaultConfig() {
+  return {
+    mcp: {
+      command: "node",
+      args: [defaultBridgePath()],
+      framing: "newline",
+      timeout_ms: 15000,
+      mutation_timeout_ms: 120000,
+      max_buffer_bytes: 10 * 1024 * 1024,
+    },
+    output: {
+      format: "human",
+      limit: 20,
+      truncate: 1200,
+    },
+    browse: {
+      limit: 20,
+      panel_truncate: 5000,
+    },
+    agent: {
+      enabled: false,
+    },
+  };
+}
+
+export function defaultBridgePath() {
+  const home = os.homedir();
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "Quill", "mcp-stdio-bridge.js");
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    return path.join(appData, "Quill", "mcp-stdio-bridge.js");
+  }
+  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  return path.join(xdgDataHome, "Quill", "mcp-stdio-bridge.js");
+}
+
+export function defaultQuillDataDir() {
+  const home = os.homedir();
+  if (process.platform === "darwin") return path.join(home, "Library", "Application Support", "Quill");
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    return path.join(appData, "Quill");
+  }
+  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  return path.join(xdgDataHome, "Quill");
+}
+
+export function supportedPlatform() {
+  return process.platform === "darwin" || process.platform === "win32";
+}
+
+export function loadConfig() {
+  return mergeConfig(defaultConfig(), readUserConfig());
+}
+
+export function configPath() {
+  if (process.env.QUILL_CONFIG) return path.resolve(process.env.QUILL_CONFIG);
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(base, "quill-cli", "config.json");
+}
+
+export function ensureConfigFile() {
+  const target = configPath();
+  if (fs.existsSync(target)) return { path: target, created: false };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(defaultConfig(), null, 2)}\n`);
+  return { path: target, created: true };
+}
+
+export function readUserConfig() {
+  const target = configPath();
+  if (!fs.existsSync(target)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(target, "utf8"));
+  } catch (error) {
+    error.code = "config_parse_error";
+    error.message = `Failed to parse config ${target}: ${error.message}`;
+    throw error;
+  }
+}
+
+export function writeUserConfig(config) {
+  const target = configPath();
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export function getConfigValue(config, key) {
+  return key.split(".").reduce((value, part) => value?.[part], config);
+}
+
+export function setConfigValue(config, key, rawValue) {
+  const parts = key.split(".");
+  let cursor = config;
+  for (const part of parts.slice(0, -1)) {
+    if (!cursor[part] || typeof cursor[part] !== "object" || Array.isArray(cursor[part])) cursor[part] = {};
+    cursor = cursor[part];
+  }
+  cursor[parts.at(-1)] = parseConfigValue(rawValue);
+  return config;
+}
+
+function parseConfigValue(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (/^-?\d+$/.test(value)) return Number.parseInt(value, 10);
+  if (/^-?\d+\.\d+$/.test(value)) return Number.parseFloat(value);
+  if ((value.startsWith("[") && value.endsWith("]")) || (value.startsWith("{") && value.endsWith("}"))) {
+    return JSON.parse(value);
+  }
+  return value;
+}
+
+function mergeConfig(base, override) {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override || {})) {
+    if (isPlainObject(value) && isPlainObject(base[key])) result[key] = mergeConfig(base[key], value);
+    else result[key] = value;
+  }
+  return result;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/doctor.js

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { defaultBridgePath, defaultQuillDataDir, supportedPlatform } from "./config.js";
+import { McpClient } from "./mcp-client.js";
+
+export const CLI_VERSION = "0.1.0";
+
+const DOWNLOAD_URL = "https://www.quillmeetings.com/download";
+const MCP_SETTINGS_HINT = "Open Quill Settings -> MCP / Integrations and enable the MCP server.";
+
+export async function runDoctorChecks(config, options = {}) {
+  const checks = [];
+  const platform = platformName();
+  const supported = supportedPlatform();
+  const quillDir = defaultQuillDataDir();
+  const defaultBridge = defaultBridgePath();
+  const configuredArgs = Array.isArray(config.mcp?.args) ? config.mcp.args : [];
+  const configuredBridge = configuredArgs[0];
+  const quillDirExists = fs.existsSync(quillDir);
+  const defaultBridgeExists = fs.existsSync(defaultBridge);
+  const configuredBridgeExists = configuredBridge ? fs.existsSync(configuredBridge) : false;
+
+  checks.push({
+    name: "Platform support",
+    status: supported ? "PASS" : "FAIL",
+    message: supported ? `${platform} is supported.` : `${platform} is not supported yet.`,
+    remediation: supported ? undefined : "Use Quill CLI on macOS or Windows.",
+  });
+
+  checks.push({
+    name: "Quill desktop data",
+    status: quillDirExists ? "PASS" : "FAIL",
+    message: quillDirExists ? `Found ${quillDir}.` : `Could not find ${quillDir}.`,
+    remediation: quillDirExists ? undefined : `Install and launch Quill desktop: ${DOWNLOAD_URL}`,
+  });
+
+  checks.push({
+    name: "Default MCP bridge",
+    status: defaultBridgeExists ? "PASS" : quillDirExists ? "FAIL" : "WARN",
+    message: defaultBridgeExists ? `Found ${defaultBridge}.` : `Could not find ${defaultBridge}.`,
+    remediation: defaultBridgeExists ? undefined : quillDirExists ? "Update Quill desktop, then run `quill doctor` again." : "Install and launch Quill desktop first.",
+  });
+
+  checks.push(configBridgeCheck(configuredBridge, configuredBridgeExists, defaultBridge, defaultBridgeExists));
+
+  const appVersion = findQuillAppVersion();
+  checks.push({
+    name: "Version info",
+    status: appVersion ? "PASS" : "WARN",
+    message: appVersion ? `CLI ${CLI_VERSION}, Quill app ${appVersion}.` : `CLI ${CLI_VERSION}, Quill app version not discovered.`,
+    remediation: appVersion ? undefined : "If MCP calls fail, update Quill desktop and rerun `quill doctor`.",
+  });
+
+  if (supported && configuredBridgeExists) {
+    checks.push(await handshakeCheck(config, options.timeoutMs));
+  } else {
+    checks.push({
+      name: "MCP handshake",
+      status: "WARN",
+      message: "Skipped because the configured bridge is not available.",
+      remediation: "Fix the bridge path above, then run `quill doctor` again.",
+    });
+  }
+
+  const failing = checks.filter((check) => check.status === "FAIL");
+  const warnings = checks.filter((check) => check.status === "WARN");
+  const firstIssue = failing[0] || warnings[0];
+  return {
+    title: "Quill doctor",
+    platform: process.platform,
+    quill_dir: quillDir,
+    default_bridge: defaultBridge,
+    configured_bridge: configuredBridge,
+    versions: {
+      cli: CLI_VERSION,
+      quill_app: appVersion || null,
+    },
+    checks,
+    issue_count: failing.length + warnings.length,
+    all_good: failing.length === 0 && warnings.length === 0,
+    start_with: firstIssue?.remediation || "Run `quill browse`.",
+  };
+}
+
+function configBridgeCheck(configuredBridge, configuredBridgeExists, defaultBridge, defaultBridgeExists) {
+  if (!configuredBridge) {
+    return {
+      name: "CLI bridge config",
+      status: "FAIL",
+      message: "Config has no mcp.args bridge path.",
+      remediation: resetBridgeCommand(defaultBridge),
+    };
+  }
+
+  if (configuredBridge === defaultBridge) {
+    return {
+      name: "CLI bridge config",
+      status: configuredBridgeExists ? "PASS" : "FAIL",
+      message: configuredBridgeExists ? "Config points at the platform default bridge." : "Config points at the platform default bridge, but the file is missing.",
+      remediation: configuredBridgeExists ? undefined : "Install or update Quill desktop.",
+    };
+  }
+
+  if (configuredBridgeExists) {
+    return {
+      name: "CLI bridge config",
+      status: "WARN",
+      message: `Config points at a custom bridge: ${configuredBridge}.`,
+      remediation: defaultBridgeExists ? resetBridgeCommand(defaultBridge) : "Keep this only if you intentionally use a custom Quill bridge.",
+    };
+  }
+
+  return {
+    name: "CLI bridge config",
+    status: "FAIL",
+    message: `Configured bridge is missing: ${configuredBridge}.`,
+    remediation: defaultBridgeExists ? resetBridgeCommand(defaultBridge) : "Install or update Quill desktop, or set mcp.args to the correct bridge path.",
+  };
+}
+
+async function handshakeCheck(config, timeoutMs = 3000) {
+  const client = new McpClient({
+    ...config.mcp,
+    timeout_ms: timeoutMs,
+  });
+
+  try {
+    await client.connect();
+    const tools = await client.listTools();
+    if (tools.length === 0) {
+      return {
+        name: "MCP handshake",
+        status: "WARN",
+        message: "Connected to the bridge, but no MCP tools were listed.",
+        remediation: MCP_SETTINGS_HINT,
+      };
+    }
+    return {
+      name: "MCP handshake",
+      status: "PASS",
+      message: `Connected and found ${tools.length} MCP tools.`,
+    };
+  } catch (error) {
+    return {
+      name: "MCP handshake",
+      status: "FAIL",
+      message: error?.code === "mcp_timeout" ? "Timed out waiting for the Quill MCP bridge." : error?.message || String(error),
+      remediation: error?.code === "mcp_timeout" ? MCP_SETTINGS_HINT : "Run `quill doctor --json` for details, then update Quill or reset the bridge path.",
+    };
+  } finally {
+    await client.close();
+  }
+}
+
+function findQuillAppVersion() {
+  if (process.platform === "darwin") {
+    const candidates = [
+      "/Applications/Quill.app/Contents/Info.plist",
+      path.join(os.homedir(), "Applications", "Quill.app", "Contents", "Info.plist"),
+    ];
+    for (const candidate of candidates) {
+      const version = readMacPlistVersion(candidate);
+      if (version) return version;
+    }
+  }
+  return null;
+}
+
+function readMacPlistVersion(file) {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, "utf8");
+  return plistStringAfterKey(text, "CFBundleShortVersionString") || plistStringAfterKey(text, "CFBundleVersion");
+}
+
+function plistStringAfterKey(text, key) {
+  const match = text.match(new RegExp(`<key>${key}<\\/key>\\s*<string>([^<]+)<\\/string>`));
+  return match?.[1] || null;
+}
+
+function resetBridgeCommand(defaultBridge) {
+  return `Run \`quill config set mcp.args '${JSON.stringify([defaultBridge])}'\`.`;
+}
+
+function platformName() {
+  if (process.platform === "darwin") return "macOS";
+  if (process.platform === "win32") return "Windows";
+  if (process.platform === "linux") return "Linux";
+  return process.platform;
+}

package/src/format.js

@@ -0,0 +1,275 @@
+export function printData(data, options = {}) {
+  data = shapeForOutput(data, options);
+  const format = options.format || "human";
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    return;
+  }
+
+  if (format === "human" || options.human) {
+    const rendered = toHuman(data);
+    if (rendered) {
+      process.stdout.write(`${rendered}\n`);
+      return;
+    }
+  }
+
+  process.stdout.write(`${toToon(data)}\n`);
+}
+
+export function shapeForOutput(data, options = {}) {
+  const cloned = clone(data);
+  applyFieldSelection(cloned, options);
+  if (!options.full) truncateLargeStrings(cloned, Number.parseInt(options.truncate || "1200", 10));
+  return cloned;
+}
+
+export function toHuman(data) {
+  const result = data?.result || data;
+  if (!result || typeof result !== "object") return null;
+
+  if (result.bin && result.description) return toStatusScreen(result, data.help);
+  if (result.config_path && result.mcp_bridge) return toStatusScreen({ title: "Quill setup", ...result }, data.help);
+  if (result.title === "Quill doctor" && Array.isArray(result.checks)) return toDoctorScreen(result);
+
+  for (const key of ["meetings", "events", "contacts", "templates", "threads", "notes"]) {
+    if (Array.isArray(result[key])) {
+      const rows = result[key].map((item) => humanizeRow(item));
+      const title = `${capitalize(key)} (${result.count ?? rows.length})`;
+      const help = Array.isArray(data.help) ? `\n\n${data.help.join("\n")}` : "";
+      return `${title}\n${toTable(rows)}${help}`;
+    }
+  }
+
+  if (typeof result.message === "string") return result.message;
+  return null;
+}
+
+function toDoctorScreen(result) {
+  const lines = [result.title, ""];
+  for (const check of result.checks) {
+    lines.push(`${check.status.padEnd(4)} ${check.name}: ${check.message}`);
+    if (check.remediation) lines.push(`     ${check.remediation}`);
+  }
+  lines.push("");
+  if (result.all_good) {
+    lines.push("All good. Run `quill browse`.");
+  } else {
+    lines.push(`${result.issue_count} issue${result.issue_count === 1 ? "" : "s"} - start with: ${result.start_with}`);
+  }
+  return lines.join("\n");
+}
+
+function toStatusScreen(data, help) {
+  const lines = [
+    `${data.bin || data.title}`,
+  ];
+  if (data.description) lines.push(data.description);
+  const rows = Object.entries(data)
+    .filter(([key]) => !["bin", "title", "description", "next", "help"].includes(key))
+    .map(([key, value]) => [humanLabel(key), formatHumanValue(value)]);
+
+  if (rows.length > 0) {
+    lines.push("");
+    const width = Math.max(...rows.map(([key]) => key.length));
+    lines.push(...rows.map(([key, value]) => `${key.padEnd(width)}  ${value}`));
+  }
+
+  if (data.next) lines.push("", data.next);
+  else if (Array.isArray(help) && help.length > 0) lines.push("", ...help);
+  return lines.join("\n");
+}
+
+export function toToon(value, indent = 0, key = null) {
+  const pad = " ".repeat(indent);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return key ? `${pad}${key}[0]:` : `${pad}items[0]:`;
+    if (value.every(isFlatObject)) {
+      const fields = collectFields(value);
+      const header = key ? `${key}[${value.length}]{${fields.join(",")}}:` : `items[${value.length}]{${fields.join(",")}}:`;
+      const rows = value.map((item) => `${pad}  ${fields.map((field) => scalar(item[field])).join(",")}`);
+      return [`${pad}${header}`, ...rows].join("\n");
+    }
+    const header = key ? `${pad}${key}[${value.length}]:` : `${pad}items[${value.length}]:`;
+    return [header, ...value.map((item) => toToon(item, indent + 2))].join("\n");
+  }
+
+  if (isObject(value)) {
+    const lines = [];
+    if (key) lines.push(`${pad}${key}:`);
+    for (const [childKey, childValue] of Object.entries(value)) {
+      if (Array.isArray(childValue) || isObject(childValue)) {
+        lines.push(toToon(childValue, key ? indent + 2 : indent, childKey));
+      } else {
+        lines.push(`${key ? " ".repeat(indent + 2) : pad}${childKey}: ${scalar(childValue)}`);
+      }
+    }
+    return lines.join("\n");
+  }
+
+  return key ? `${pad}${key}: ${scalar(value)}` : `${pad}${scalar(value)}`;
+}
+
+export function structuredError(code, message, details = undefined) {
+  const error = { code, message };
+  if (details !== undefined) error.details = details;
+  return { error };
+}
+
+export function withHelp(data, commands) {
+  return {
+    ...data,
+    help: commands,
+  };
+}
+
+export function truncateText(value, limit = 1200) {
+  if (typeof value !== "string" || value.length <= limit) return value;
+  return `${value.slice(0, limit)}... (truncated, ${value.length} chars total; use --full to see complete text)`;
+}
+
+function collectFields(items) {
+  const preferred = ["id", "title", "name", "date", "start", "duration", "status"];
+  const keys = [...new Set(items.flatMap((item) => Object.keys(item)))];
+  const sorted = [...preferred.filter((key) => keys.includes(key)), ...keys.filter((key) => !preferred.includes(key))];
+  return sorted.slice(0, 4);
+}
+
+function isFlatObject(value) {
+  return isObject(value) && Object.values(value).every((child) => !Array.isArray(child) && !isObject(child));
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function scalar(value) {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") {
+    const normalized = value.replace(/\r?\n/g, "\\n");
+    return /[,"\n]/.test(normalized) ? JSON.stringify(normalized) : normalized;
+  }
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return String(value);
+}
+
+function humanizeRow(item) {
+  const row = { ...item };
+  for (const key of ["date", "start", "end", "started_at", "created_at"]) {
+    if (row[key]) row[key] = relativeTime(row[key]);
+  }
+  return row;
+}
+
+function relativeTime(value) {
+  const time = new Date(value).getTime();
+  if (Number.isNaN(time)) return value;
+  const seconds = Math.round((time - Date.now()) / 1000);
+  const abs = Math.abs(seconds);
+  const units = [
+    ["year", 31536000],
+    ["month", 2592000],
+    ["week", 604800],
+    ["day", 86400],
+    ["hour", 3600],
+    ["minute", 60],
+  ];
+  for (const [name, size] of units) {
+    if (abs >= size) {
+      const amount = Math.round(abs / size);
+      return seconds < 0 ? `${amount} ${name}${amount === 1 ? "" : "s"} ago` : `in ${amount} ${name}${amount === 1 ? "" : "s"}`;
+    }
+  }
+  return seconds < 0 ? "just now" : "now";
+}
+
+function toTable(rows) {
+  if (rows.length === 0) return "(none)";
+  const fields = collectFields(rows);
+  const widths = fields.map((field) => Math.max(field.length, ...rows.map((row) => truncateCell(row[field]).length)));
+  const header = fields.map((field, index) => field.padEnd(widths[index])).join("  ");
+  const divider = widths.map((width) => "-".repeat(width)).join("  ");
+  const body = rows.map((row) => fields.map((field, index) => truncateCell(row[field]).padEnd(widths[index])).join("  "));
+  return [header, divider, ...body].join("\n");
+}
+
+function truncateCell(value) {
+  const text = value === null || value === undefined ? "" : String(value).replace(/\s+/g, " ");
+  return text.length > 48 ? `${text.slice(0, 45)}...` : text;
+}
+
+function formatHumanValue(value) {
+  if (value === true) return "yes";
+  if (value === false) return "no";
+  if (Array.isArray(value)) return value.join(", ");
+  if (isObject(value)) return JSON.stringify(value);
+  return value === null || value === undefined ? "" : String(value);
+}
+
+function humanLabel(value) {
+  return String(value)
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (char) => char.toUpperCase())
+    .replace(/\bMcp\b/g, "MCP");
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function clone(value) {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function applyFieldSelection(data, options) {
+  const fields = options.fields;
+  const collections = findCollections(data);
+  for (const collection of collections) {
+    const selected = fields || defaultFieldsFor(collection.key);
+    if (!selected) continue;
+    collection.items.forEach((item) => {
+      for (const key of Object.keys(item)) {
+        if (!selected.includes(key)) delete item[key];
+      }
+    });
+  }
+}
+
+function findCollections(value, collections = []) {
+  if (!isObject(value)) return collections;
+  for (const [key, child] of Object.entries(value)) {
+    if (Array.isArray(child) && child.every(isFlatObject)) {
+      collections.push({ key, items: child });
+    } else if (isObject(child)) {
+      findCollections(child, collections);
+    }
+  }
+  return collections;
+}
+
+function defaultFieldsFor(key) {
+  const fields = {
+    meetings: ["id", "title", "date", "duration"],
+    events: ["id", "title", "start", "end"],
+    contacts: ["id", "name", "email"],
+    templates: ["id", "name", "kind", "verb"],
+    threads: ["id", "title", "updated_at"],
+    notes: ["id", "title", "template_id", "created_at"],
+    tools: ["name", "description"],
+  };
+  return fields[key];
+}
+
+function truncateLargeStrings(value, limit) {
+  if (Array.isArray(value)) {
+    value.forEach((item) => truncateLargeStrings(item, limit));
+    return;
+  }
+  if (!isObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (typeof child === "string") value[key] = truncateText(child, limit);
+    else truncateLargeStrings(child, limit);
+  }
+}