npm - @hasna/contacts - Versions diffs - 0.1.0 → 0.2.0 - Mend

@hasna/contacts 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/dashboard/dist/assets/index-0l6aQb1t.css +1 -0
package/dashboard/dist/assets/index-opnZdkVD.js +229 -0
package/dashboard/dist/index.html +2 -2
package/dist/cli/index.js +530 -16
package/dist/db/companies.d.ts.map +1 -1
package/dist/db/companies.test.d.ts +2 -0
package/dist/db/companies.test.d.ts.map +1 -0
package/dist/db/contacts.d.ts +1 -0
package/dist/db/contacts.d.ts.map +1 -1
package/dist/db/contacts.test.d.ts +2 -0
package/dist/db/contacts.test.d.ts.map +1 -0
package/dist/db/database.d.ts +1 -0
package/dist/db/database.d.ts.map +1 -1
package/dist/db/groups.d.ts +12 -0
package/dist/db/groups.d.ts.map +1 -0
package/dist/db/relationships.test.d.ts +2 -0
package/dist/db/relationships.test.d.ts.map +1 -0
package/dist/db/tags.d.ts.map +1 -1
package/dist/db/tags.test.d.ts +2 -0
package/dist/db/tags.test.d.ts.map +1 -0
package/dist/index.d.ts +3 -2
package/dist/index.d.ts.map +1 -1
package/dist/index.js +102 -5
package/dist/lib/config.d.ts +7 -0
package/dist/lib/config.d.ts.map +1 -0
package/dist/lib/dedup.d.ts +10 -0
package/dist/lib/dedup.d.ts.map +1 -0
package/dist/lib/import.test.d.ts +2 -0
package/dist/lib/import.test.d.ts.map +1 -0
package/dist/mcp/index.js +567 -76
package/dist/mcp/mcp.test.d.ts +2 -0
package/dist/mcp/mcp.test.d.ts.map +1 -0
package/dist/server/index.js +38 -3
package/dist/types/index.d.ts +25 -0
package/dist/types/index.d.ts.map +1 -1
package/package.json +1 -1
package/dashboard/dist/assets/index-B4ndI7Qt.js +0 -49
package/dashboard/dist/assets/index-C5bn2HWO.css +0 -1

package/dashboard/dist/index.html CHANGED Viewed

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Open Contacts</title>
-    <script type="module" crossorigin src="/assets/index-B4ndI7Qt.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-C5bn2HWO.css">
+    <script type="module" crossorigin src="/assets/index-opnZdkVD.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-0l6aQb1t.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/cli/index.js CHANGED Viewed

@@ -2093,6 +2093,14 @@ var init_types = __esm(() => {
 });
 // src/db/database.ts
+var exports_database = {};
+__export(exports_database, {
+  uuid: () => uuid,
+  resetDatabase: () => resetDatabase,
+  now: () => now,
+  getDbPath: () => getDbPath,
+  getDatabase: () => getDatabase
+});
 import { Database } from "bun:sqlite";
 import { existsSync, mkdirSync } from "fs";
 import { dirname, join, resolve } from "path";
@@ -2121,6 +2129,9 @@ function getDatabase(path) {
   _db = db;
   return db;
 }
+function resetDatabase() {
+  _db = null;
+}
 function uuid() {
   return crypto.randomUUID();
 }
@@ -2303,6 +2314,25 @@ var init_database = __esm(() => {
   END;
   CREATE TABLE IF NOT EXISTS _migrations (version INTEGER PRIMARY KEY);
+  `,
+    `
+  ALTER TABLE contacts ADD COLUMN last_contacted_at TEXT;
+  ALTER TABLE contacts ADD COLUMN website TEXT;
+  ALTER TABLE contacts ADD COLUMN preferred_contact_method TEXT;
+  CREATE TABLE IF NOT EXISTS groups (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    description TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+  CREATE TABLE IF NOT EXISTS contact_groups (
+    contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+    group_id TEXT NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
+    PRIMARY KEY (contact_id, group_id)
+  );
   `
   ];
 });
@@ -2322,7 +2352,8 @@ function rowToContact(row) {
   return {
     ...row,
     source: row.source,
-    custom_fields: JSON.parse(row.custom_fields || "{}")
+    custom_fields: JSON.parse(row.custom_fields || "{}"),
+    preferred_contact_method: row.preferred_contact_method ?? null
   };
 }
 function rowToEmail(row) {
@@ -2403,8 +2434,8 @@ function createContact(input, db) {
   const firstName = input.first_name ?? "";
   const lastName = input.last_name ?? "";
   const displayName = input.display_name ?? (firstName || lastName ? `${firstName} ${lastName}`.trim() : "Unnamed Contact");
-  d.run(`INSERT INTO contacts (id, first_name, last_name, display_name, nickname, avatar_url, notes, birthday, company_id, job_title, source, custom_fields, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+  d.run(`INSERT INTO contacts (id, first_name, last_name, display_name, nickname, avatar_url, notes, birthday, company_id, job_title, source, custom_fields, last_contacted_at, website, preferred_contact_method, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
     id,
     firstName,
     lastName,
@@ -2417,6 +2448,9 @@ function createContact(input, db) {
     input.job_title ?? null,
     input.source ?? "manual",
     JSON.stringify(input.custom_fields ?? {}),
+    input.last_contacted_at ?? null,
+    input.website ?? null,
+    input.preferred_contact_method ?? null,
     timestamp,
     timestamp
   ]);
@@ -2528,6 +2562,18 @@ function updateContact(id, input, db) {
     setClauses.push("custom_fields = ?");
     params.push(JSON.stringify(input.custom_fields));
   }
+  if (input.last_contacted_at !== undefined) {
+    setClauses.push("last_contacted_at = ?");
+    params.push(input.last_contacted_at);
+  }
+  if (input.website !== undefined) {
+    setClauses.push("website = ?");
+    params.push(input.website);
+  }
+  if (input.preferred_contact_method !== undefined) {
+    setClauses.push("preferred_contact_method = ?");
+    params.push(input.preferred_contact_method);
+  }
   params.push(id);
   d.run(`UPDATE contacts SET ${setClauses.join(", ")} WHERE id = ?`, params);
   logActivity(d, { contact_id: id, action: "contact.updated", details: `Updated contact: ${existing.display_name}` });
@@ -2573,6 +2619,11 @@ function searchContacts(query, db) {
   }
   return allRows.map((row) => loadContactDetails(d, rowToContact(row)));
 }
+function listRecentContacts(limit, db) {
+  const d = db || getDatabase();
+  const rows = d.query(`SELECT * FROM contacts ORDER BY updated_at DESC LIMIT ?`).all(limit);
+  return rows.map((row) => loadContactDetails(d, rowToContact(row)));
+}
 var init_contacts = __esm(() => {
   init_types();
   init_database();
@@ -3256,8 +3307,8 @@ var exports_serve = {};
 __export(exports_serve, {
   startServer: () => startServer
 });
-import { existsSync as existsSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
 function json(data, status = 200) {
   return new Response(JSON.stringify(data), {
     status,
@@ -3463,7 +3514,7 @@ async function handleExport(req) {
   });
 }
 function serveStaticFile(filePath) {
-  if (!existsSync2(filePath))
+  if (!existsSync3(filePath))
     return null;
   return new Response(Bun.file(filePath));
 }
@@ -3507,8 +3558,8 @@ function startServer(port) {
               response = apiError("Not found", 404);
           }
         } else {
-          const filePath = join2(DASHBOARD_DIST, url.pathname === "/" ? "index.html" : url.pathname);
-          response = serveStaticFile(filePath) ?? serveStaticFile(join2(DASHBOARD_DIST, "index.html")) ?? new Response("Not Found", { status: 404 });
+          const filePath = join3(DASHBOARD_DIST, url.pathname === "/" ? "index.html" : url.pathname);
+          response = serveStaticFile(filePath) ?? serveStaticFile(join3(DASHBOARD_DIST, "index.html")) ?? new Response("Not Found", { status: 404 });
         }
       } catch (err) {
         console.error("Request error:", err);
@@ -3529,7 +3580,7 @@ var init_serve = __esm(() => {
   init_contacts();
   init_companies();
   init_tags();
-  DASHBOARD_DIST = join2(import.meta.dir, "../../dashboard/dist");
+  DASHBOARD_DIST = join3(import.meta.dir, "../../dashboard/dist");
 });
 // node_modules/commander/esm.mjs
@@ -3553,8 +3604,85 @@ init_contacts();
 init_companies();
 init_tags();
 import chalk from "chalk";
-import { readFileSync, writeFileSync, existsSync as existsSync3 } from "fs";
-import { extname } from "path";
+// src/db/groups.ts
+init_database();
+function createGroup(db, input) {
+  const id = uuid();
+  db.query(`INSERT INTO groups(id, name, description, created_at, updated_at) VALUES(?,?,?,?,?)`).run(id, input.name, input.description ?? null, now(), now());
+  return getGroup(db, id);
+}
+function getGroup(db, id) {
+  return db.query(`SELECT * FROM groups WHERE id = ?`).get(id);
+}
+function listGroups(db) {
+  return db.query(`SELECT g.*, COUNT(cg.contact_id) as member_count FROM groups g LEFT JOIN contact_groups cg ON g.id = cg.group_id GROUP BY g.id ORDER BY g.name`).all();
+}
+function addContactToGroup(db, contactId, groupId) {
+  db.query(`INSERT OR IGNORE INTO contact_groups(contact_id, group_id) VALUES(?,?)`).run(contactId, groupId);
+}
+function removeContactFromGroup(db, contactId, groupId) {
+  db.query(`DELETE FROM contact_groups WHERE contact_id = ? AND group_id = ?`).run(contactId, groupId);
+}
+function listContactsInGroup(db, groupId) {
+  const rows = db.query(`SELECT contact_id FROM contact_groups WHERE group_id = ?`).all(groupId);
+  return rows.map((r) => r.contact_id);
+}
+// src/cli/index.tsx
+init_database();
+// src/lib/dedup.ts
+function findEmailDuplicates(db) {
+  const rows = db.query(`
+    SELECT e.address as email, GROUP_CONCAT(e.contact_id) as ids
+    FROM emails e
+    WHERE e.contact_id IS NOT NULL
+    GROUP BY LOWER(e.address)
+    HAVING COUNT(*) > 1
+  `).all();
+  return rows.map((r) => ({ email: r.email, contact_ids: r.ids.split(",") }));
+}
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_2, j) => i === 0 ? j : j === 0 ? i : 0));
+  for (let i = 1;i <= m; i++)
+    for (let j = 1;j <= n; j++)
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+  return dp[m][n];
+}
+function findNameDuplicates(db) {
+  const contacts = db.query(`SELECT id, display_name FROM contacts`).all();
+  const pairs = [];
+  for (let i = 0;i < contacts.length; i++) {
+    for (let j = i + 1;j < contacts.length; j++) {
+      const dist = levenshtein(contacts[i].display_name.toLowerCase(), contacts[j].display_name.toLowerCase());
+      if (dist <= 2 && dist > 0) {
+        pairs.push({ contact_ids: [contacts[i].id, contacts[j].id], similarity: dist });
+      }
+    }
+  }
+  return pairs;
+}
+// src/lib/config.ts
+import { existsSync as existsSync2, readFileSync, writeFileSync, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+var CONFIG_DIR = join2(process.env["HOME"] || "~", ".contacts");
+var CONFIG_FILE = join2(CONFIG_DIR, "config.json");
+function readConfig() {
+  if (!existsSync2(CONFIG_FILE))
+    return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+// src/cli/index.tsx
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync4, copyFileSync, statSync, mkdirSync as mkdirSync3, readdirSync } from "fs";
+import { extname, join as join4 } from "path";
 function renderTable(headers, rows) {
   const colWidths = headers.map((h) => h.length);
   for (const row of rows) {
@@ -3660,7 +3788,43 @@ async function confirm(question) {
   return answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
 }
 program.name("contacts").description("Open Contacts \u2014 contact management for AI coding agents").version("0.1.0");
-program.command("add").description("Add a new contact interactively").action(async () => {
+function collect(val, prev) {
+  return [...prev, val];
+}
+program.command("add").description("Add a new contact (interactive or via flags)").option("--first <name>", "First name").option("--last <name>", "Last name").option("--display <name>", "Display name").option("--email <email>", "Email address").option("--phone <phone>", "Phone number").option("--title <title>", "Job title").option("--company <id>", "Company ID").option("--tag <tag>", "Tag name (can specify multiple times)", collect, []).option("--note <text>", "Notes").option("--website <url>", "Website URL").action(async (opts) => {
+  if (opts.first || opts.last || opts.display) {
+    const firstName = opts.first ?? "";
+    const lastName = opts.last ?? "";
+    const displayName = opts.display ?? (`${firstName} ${lastName}`.trim() || "Unnamed Contact");
+    const input2 = {
+      display_name: displayName,
+      first_name: firstName || undefined,
+      last_name: lastName || undefined,
+      job_title: opts.title || undefined,
+      notes: opts.note || undefined,
+      website: opts.website || undefined,
+      company_id: opts.company || undefined,
+      emails: opts.email ? [{ address: opts.email, type: "work", is_primary: true }] : undefined,
+      phones: opts.phone ? [{ number: opts.phone, type: "mobile", is_primary: true }] : undefined
+    };
+    const contact2 = createContact(input2);
+    if (opts.tag.length > 0) {
+      const db = getDatabase();
+      const allTags = listTags();
+      for (const tagName of opts.tag) {
+        const tag = allTags.find((t) => t.name === tagName);
+        if (tag) {
+          db.run(`INSERT OR IGNORE INTO contact_tags (contact_id, tag_id) VALUES (?, ?)`, [contact2.id, tag.id]);
+        } else {
+          console.log(chalk.yellow(`  ! Tag not found: ${tagName} (skipped)`));
+        }
+      }
+    }
+    console.log(chalk.green(`
+\u2713 Contact created: ${contact2.display_name} (${contact2.id})
+`));
+    return;
+  }
   console.log(chalk.bold.blue(`
 Add New Contact
 `));
@@ -3718,8 +3882,40 @@ program.command("show <id>").description("Show full contact details").action((id
   const contact = getContact(id);
   formatContact(contact);
 });
-program.command("edit <id>").description("Edit a contact interactively").action(async (id) => {
+program.command("edit <id>").description("Edit a contact (interactive or via flags)").option("--first <name>", "First name").option("--last <name>", "Last name").option("--display <name>", "Display name").option("--email <email>", "Email address").option("--phone <phone>", "Phone number").option("--title <title>", "Job title").option("--note <text>", "Notes").option("--website <url>", "Website URL").action(async (id, opts) => {
   const contact = getContact(id);
+  const hasFlags = opts.first || opts.last || opts.display || opts.email || opts.phone || opts.title || opts.note || opts.website;
+  if (hasFlags) {
+    const updates2 = {};
+    if (opts.first !== undefined)
+      updates2.first_name = opts.first;
+    if (opts.last !== undefined)
+      updates2.last_name = opts.last;
+    if (opts.display !== undefined)
+      updates2.display_name = opts.display;
+    if (opts.title !== undefined)
+      updates2.job_title = opts.title;
+    if (opts.note !== undefined)
+      updates2.notes = opts.note;
+    if (opts.website !== undefined)
+      updates2.website = opts.website;
+    const updated2 = updateContact(id, updates2);
+    if (opts.email) {
+      const db = getDatabase();
+      const { uuid: uuid2 } = await Promise.resolve().then(() => (init_database(), exports_database));
+      db.run(`INSERT INTO emails (id, contact_id, company_id, address, type, is_primary) VALUES (?, ?, NULL, ?, 'work', 0)`, [uuid2(), id, opts.email]);
+    }
+    if (opts.phone) {
+      const db = getDatabase();
+      const { uuid: uuid2 } = await Promise.resolve().then(() => (init_database(), exports_database));
+      db.run(`INSERT INTO phones (id, contact_id, company_id, number, country_code, type, is_primary) VALUES (?, ?, NULL, ?, NULL, 'mobile', 0)`, [uuid2(), id, opts.phone]);
+    }
+    console.log(chalk.green(`
+\u2713 Contact updated: ${updated2.display_name}
+`));
+    formatContact(getContact(id));
+    return;
+  }
   console.log(chalk.bold.blue(`
 Editing: ${contact.display_name}
 `));
@@ -3729,6 +3925,7 @@ Editing: ${contact.display_name}
   const first_name = await prompt(`First name [${contact.first_name}]:`);
   const last_name = await prompt(`Last name [${contact.last_name}]:`);
   const job_title = await prompt(`Job title [${contact.job_title ?? ""}]:`);
+  const website = await prompt(`Website [${contact.website ?? ""}]:`);
   const notes = await prompt(`Notes [${contact.notes ? contact.notes.slice(0, 30) + "..." : ""}]:`);
   const updates = {};
   if (display_name)
@@ -3739,6 +3936,8 @@ Editing: ${contact.display_name}
     updates.last_name = last_name;
   if (job_title)
     updates.job_title = job_title;
+  if (website)
+    updates.website = website;
   if (notes)
     updates.notes = notes;
   if (Object.keys(updates).length === 0) {
@@ -3894,7 +4093,7 @@ Add New Tag
 `));
 });
 program.command("import <file>").description("Import contacts from CSV, vCard (.vcf), or JSON file").action(async (file) => {
-  if (!existsSync3(file)) {
+  if (!existsSync4(file)) {
     console.error(chalk.red(`
 File not found: ${file}
 `));
@@ -3914,7 +4113,7 @@ Unsupported file type: ${ext}. Use .csv, .vcf, or .json
 `));
     process.exit(1);
   }
-  const data = readFileSync(file, "utf8");
+  const data = readFileSync2(file, "utf8");
   console.log(chalk.blue(`
 Importing ${format.toUpperCase()} from ${file}...
 `));
@@ -3945,7 +4144,7 @@ Invalid format: ${format}. Use csv, vcf, or json
   const { contacts } = listContacts({ limit: 1e5 });
   const output = await exportContacts(format, contacts);
   if (opts.output) {
-    writeFileSync(opts.output, output, "utf8");
+    writeFileSync2(opts.output, output, "utf8");
     console.log(chalk.green(`
 \u2713 Exported ${contacts.length} contact(s) to ${opts.output}
 `));
@@ -3989,4 +4188,319 @@ ${chalk.bold("Available tools (24 total):")}
   ${chalk.gray("I/O:      ")}${chalk.white("import_contacts  export_contacts  get_stats")}
 `);
 });
+program.command("open [id]").description("Open the web dashboard in browser").action(async (id) => {
+  const port = 19428;
+  const url = id ? `http://localhost:${port}/#/contacts/${id}` : `http://localhost:${port}`;
+  const platform = process.platform;
+  const opener = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+  const proc = Bun.spawn([opener, url], { stdio: ["ignore", "ignore", "ignore"] });
+  await proc.exited;
+  console.log(chalk.green(`Opening ${url}`));
+});
+program.command("recent").description("Show recently added or modified contacts").option("--limit <n>", "Number to show", "10").action((opts) => {
+  const limit = parseInt(opts.limit, 10);
+  const contacts = listRecentContacts(limit);
+  if (contacts.length === 0) {
+    console.log(chalk.gray(`
+No contacts found.
+`));
+    return;
+  }
+  console.log();
+  const rows = contacts.map((c) => ({
+    Name: c.display_name,
+    Company: c.company?.name ?? "",
+    Email: c.emails?.[0]?.address ?? "",
+    Phone: c.phones?.[0]?.number ?? "",
+    Updated: c.updated_at.slice(0, 10)
+  }));
+  renderTable(["Name", "Company", "Email", "Phone", "Updated"], rows);
+  console.log(chalk.gray(`
+${contacts.length} recent contact(s)
+`));
+});
+program.command("dupe").description("Find potential duplicate contacts").action(() => {
+  const db = getDatabase();
+  const emailDupes = findEmailDuplicates(db);
+  const nameDupes = findNameDuplicates(db);
+  let total = 0;
+  if (emailDupes.length > 0) {
+    console.log(chalk.bold.yellow(`
+Duplicate Emails:
+`));
+    for (const group of emailDupes) {
+      console.log(`  ${chalk.cyan(group.email)}`);
+      for (const cid of group.contact_ids) {
+        try {
+          const c = getContact(cid);
+          console.log(`    ${chalk.gray(cid)}  ${c.display_name}`);
+        } catch {
+          console.log(`    ${chalk.gray(cid)}  (not found)`);
+        }
+      }
+      console.log();
+      total++;
+    }
+  }
+  if (nameDupes.length > 0) {
+    console.log(chalk.bold.yellow(`Similar Names:
+`));
+    for (const pair of nameDupes) {
+      try {
+        const a = getContact(pair.contact_ids[0]);
+        const b = getContact(pair.contact_ids[1]);
+        console.log(`  ${chalk.magenta(a.display_name)}  \u2194  ${chalk.magenta(b.display_name)}  ${chalk.gray(`(distance: ${pair.similarity})`)}`);
+        console.log(`    ${chalk.gray(pair.contact_ids[0])}  vs  ${chalk.gray(pair.contact_ids[1])}`);
+        console.log();
+        total++;
+      } catch {}
+    }
+  }
+  if (total === 0) {
+    console.log(chalk.green(`
+No duplicates found.
+`));
+  } else {
+    console.log(chalk.gray(`Found ${total} duplicate group(s). Use 'contacts show <id>' to inspect and 'contacts delete <id>' to clean up.
+`));
+  }
+});
+program.command("log <id>").description("Log a contact interaction (sets last_contacted_at)").option("--note <text>", "Note to append").option("--date <YYYY-MM-DD>", "Date of contact (default: today)").action((id, opts) => {
+  const contact = getContact(id);
+  const date = opts.date ?? new Date().toISOString().slice(0, 10);
+  const updates = {
+    last_contacted_at: date
+  };
+  if (opts.note) {
+    const existing = contact.notes ?? "";
+    const separator = existing ? `
+` : "";
+    updates.notes = `${existing}${separator}[${date}] ${opts.note}`;
+  }
+  const updated = updateContact(id, updates);
+  console.log(chalk.green(`
+\u2713 Logged contact with ${updated.display_name} on ${date}
+`));
+  if (opts.note) {
+    console.log(chalk.gray(`  Note: ${opts.note}
+`));
+  }
+});
+var groupsCmd = program.command("groups").description("Manage contact groups").action(() => {
+  const db = getDatabase();
+  const groups = listGroups(db);
+  if (groups.length === 0) {
+    console.log(chalk.gray(`
+No groups found.
+`));
+    return;
+  }
+  console.log();
+  const rows = groups.map((g) => ({
+    ID: g.id,
+    Name: g.name,
+    Description: g.description ?? "",
+    Members: String(g.member_count ?? 0)
+  }));
+  renderTable(["ID", "Name", "Description", "Members"], rows);
+  console.log(chalk.gray(`
+${groups.length} group(s)
+`));
+});
+groupsCmd.command("add").description("Create a new group").option("--name <name>", "Group name (required)").option("--description <desc>", "Description").action(async (opts) => {
+  const db = getDatabase();
+  let name = opts.name;
+  if (!name) {
+    name = await prompt("Group name (required):");
+    if (!name) {
+      console.error(chalk.red("Group name is required."));
+      process.exit(1);
+    }
+  }
+  const group = createGroup(db, { name, description: opts.description });
+  console.log(chalk.green(`
+\u2713 Group created: ${group.name} (${group.id})
+`));
+});
+groupsCmd.command("show <id>").description("Show group details with members").action((id) => {
+  const db = getDatabase();
+  const group = getGroup(db, id);
+  if (!group) {
+    console.error(chalk.red(`
+Group not found: ${id}
+`));
+    process.exit(1);
+  }
+  console.log(`
+` + chalk.bold.blue("\u2501\u2501\u2501 Group: ") + chalk.bold(group.name) + chalk.bold.blue(" \u2501\u2501\u2501"));
+  if (group.description)
+    console.log(chalk.gray("  Description: ") + group.description);
+  console.log(chalk.gray(`  ID: ${group.id}`));
+  console.log();
+  const memberIds = listContactsInGroup(db, id);
+  if (memberIds.length === 0) {
+    console.log(chalk.gray(`  No members.
+`));
+    return;
+  }
+  console.log(chalk.yellow(`  Members (${memberIds.length}):
+`));
+  for (const cid of memberIds) {
+    try {
+      const c = getContact(cid);
+      console.log(`    ${chalk.bold(c.display_name)}  ${chalk.gray(cid)}`);
+    } catch {
+      console.log(`    ${chalk.gray(cid)}  (not found)`);
+    }
+  }
+  console.log();
+});
+groupsCmd.command("add-member <group-id> <contact-id>").description("Add a contact to a group").action((groupId, contactId) => {
+  const db = getDatabase();
+  const group = getGroup(db, groupId);
+  if (!group) {
+    console.error(chalk.red(`
+Group not found: ${groupId}
+`));
+    process.exit(1);
+  }
+  const contact = getContact(contactId);
+  addContactToGroup(db, contactId, groupId);
+  console.log(chalk.green(`
+\u2713 Added ${contact.display_name} to group ${group.name}
+`));
+});
+groupsCmd.command("remove-member <group-id> <contact-id>").description("Remove a contact from a group").action((groupId, contactId) => {
+  const db = getDatabase();
+  const group = getGroup(db, groupId);
+  if (!group) {
+    console.error(chalk.red(`
+Group not found: ${groupId}
+`));
+    process.exit(1);
+  }
+  const contact = getContact(contactId);
+  removeContactFromGroup(db, contactId, groupId);
+  console.log(chalk.green(`
+\u2713 Removed ${contact.display_name} from group ${group.name}
+`));
+});
+program.command("init").description("Show setup info, stats, and configuration").action(() => {
+  const dbPath = getDbPath();
+  const config = readConfig();
+  console.log(chalk.bold.blue(`
+\u2501\u2501\u2501 Open Contacts Setup \u2501\u2501\u2501
+`));
+  console.log(chalk.gray("  DB path:    ") + (config.db_path ?? dbPath));
+  console.log();
+  try {
+    const db = getDatabase();
+    const contactCount = db.query("SELECT COUNT(*) as n FROM contacts").get().n;
+    const companyCount = db.query("SELECT COUNT(*) as n FROM companies").get().n;
+    const tagCount = db.query("SELECT COUNT(*) as n FROM tags").get().n;
+    console.log(chalk.bold("  Stats:"));
+    console.log(`    ${chalk.cyan(String(contactCount))} contacts`);
+    console.log(`    ${chalk.cyan(String(companyCount))} companies`);
+    console.log(`    ${chalk.cyan(String(tagCount))} tags`);
+  } catch {
+    console.log(chalk.gray("  (Database not yet initialized)"));
+  }
+  console.log();
+  console.log(chalk.bold("  MCP Setup (Claude Code):"));
+  console.log("    " + chalk.cyan("claude mcp add --transport stdio --scope user contacts -- contacts-mcp"));
+  console.log();
+  console.log(chalk.bold("  Shell Completion (zsh):"));
+  console.log("    " + chalk.cyan("contacts completion zsh > ~/.zsh/completions/_contacts"));
+  console.log("    " + chalk.cyan("contacts completion bash >> ~/.bashrc"));
+  console.log("    " + chalk.cyan("contacts completion fish > ~/.config/fish/completions/contacts.fish"));
+  console.log();
+});
+program.command("backup").description("Backup the contacts database").option("--output <path>", "Output path").option("--list", "List existing backups").action((opts) => {
+  const backupDir = join4(process.env["HOME"] || "~", ".contacts", "backups");
+  if (opts.list) {
+    if (!existsSync4(backupDir)) {
+      console.log(chalk.gray(`
+No backups found.
+`));
+      return;
+    }
+    const files = readdirSync(backupDir).filter((f) => f.endsWith(".db")).sort().reverse();
+    if (files.length === 0) {
+      console.log(chalk.gray(`
+No backups found.
+`));
+      return;
+    }
+    console.log(chalk.bold.blue(`
+Existing Backups:
+`));
+    for (const f of files) {
+      const filePath = join4(backupDir, f);
+      const size2 = statSync(filePath).size;
+      const mtime = statSync(filePath).mtime.toISOString().slice(0, 19).replace("T", " ");
+      console.log(`  ${chalk.cyan(f)}  ${chalk.gray(`${(size2 / 1024).toFixed(1)} KB  ${mtime}`)}`);
+    }
+    console.log();
+    return;
+  }
+  const src = getDbPath();
+  if (!existsSync4(src)) {
+    console.error(chalk.red(`
+Database not found: ${src}
+`));
+    process.exit(1);
+  }
+  mkdirSync3(backupDir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const dest = opts.output || join4(backupDir, `contacts-${ts}.db`);
+  copyFileSync(src, dest);
+  const size = statSync(dest).size;
+  console.log(chalk.green(`
+\u2713 Backed up to ${dest} (${(size / 1024).toFixed(1)} KB)
+`));
+});
+program.command("completion <shell>").description("Generate shell completion script (bash, zsh, fish)").action((shell) => {
+  const commands = [
+    "add",
+    "list",
+    "show",
+    "edit",
+    "delete",
+    "search",
+    "recent",
+    "dupe",
+    "log",
+    "open",
+    "import",
+    "export",
+    "companies",
+    "tags",
+    "groups",
+    "serve",
+    "mcp",
+    "init",
+    "backup",
+    "completion"
+  ];
+  if (shell === "zsh") {
+    console.log(`#compdef contacts
+_contacts() {
+  local commands=(${commands.map((c) => `'${c}'`).join(" ")})
+  _describe 'command' commands
+}
+_contacts "$@"`);
+  } else if (shell === "bash") {
+    console.log(`_contacts_completion() {
+  local cur=\${COMP_WORDS[COMP_CWORD]}
+  COMPREPLY=($(compgen -W "${commands.join(" ")}" -- "$cur"))
+}
+complete -F _contacts_completion contacts`);
+  } else if (shell === "fish") {
+    for (const c of commands) {
+      console.log(`complete -c contacts -f -a ${c}`);
+    }
+  } else {
+    console.error(chalk.red("Supported shells: bash, zsh, fish"));
+  }
+});
 program.parse(process.argv);