askshepherd 0.1.41 → 0.1.42

package/bin/shepherd-onboard.js

@@ -1,18 +1,21 @@
 #!/usr/bin/env node
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { constants as fsConstants, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, watch, writeFileSync } from "node:fs";
+import { constants as fsConstants, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, watch, writeFileSync } from "node:fs";
 import { access, chmod, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { homedir, platform } from "node:os";
 import { basename, dirname, join } from "node:path";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
+import sourceSelectionHelpers from "../source-selection.cjs";
+
+const { sourceSelectionFromSession } = sourceSelectionHelpers;
 
 const DEFAULT_API_URL = "https://brain-api-customer-facing.up.railway.app";
 const PACKAGE_NAME = "askshepherd";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
-const PACKAGE_VERSION = "0.1.40";
+const PACKAGE_VERSION = "0.1.42";
 const MCP_SERVER_NAME = "shepherd";
 const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
 const DEFAULT_AGENT_STATE_PATH = join(homedir(), ".shepherd", "raw-onboarding-agent.json");
@@ -115,18 +118,30 @@ const command = rawArgv[0] && !rawArgv[0].startsWith("--") ? rawArgv[0] : "onboa
 const args = parseArgs(command === "onboard" ? rawArgv : rawArgv.slice(1));
 let messagesPermissionNoticePrinted = false;
 
-if (command === "help" || args.help) {
-  printHelp(command === "help" ? "onboard" : command);
-  process.exit(0);
+if (isCliEntrypoint()) {
+  if (command === "help" || args.help) {
+    printHelp(command === "help" ? "onboard" : command);
+    process.exit(0);
+  }
+
+  void dispatch().catch((err) => {
+    console.error(`\nShepherd onboarding failed: ${safeError(err)}`);
+    if (args.debug === true) {
+      console.error(rawErrorDetails(err));
+    }
+    process.exit(1);
+  });
 }
 
-void dispatch().catch((err) => {
-  console.error(`\nShepherd onboarding failed: ${safeError(err)}`);
-  if (args.debug === true) {
-    console.error(rawErrorDetails(err));
+function isCliEntrypoint() {
+  if (!process.argv[1]) return false;
+  const modulePath = fileURLToPath(import.meta.url);
+  try {
+    return realpathSync(modulePath) === realpathSync(process.argv[1]);
+  } catch {
+    return modulePath === process.argv[1];
   }
-  process.exit(1);
-});
+}
 
 async function dispatch() {
   if (command === "onboard") {
@@ -153,6 +168,10 @@ async function dispatch() {
     await runWriteMessagesConfig();
   } else if (command === "install-messages-agent") {
     await runInstallMessagesAgent();
+  } else if (command === "write-coding-sessions-config") {
+    await runWriteCodingSessionsConfig();
+  } else if (command === "install-coding-sessions-agent") {
+    await runInstallCodingSessionsAgent();
   } else if (command === "coding-sessions-agent") {
     await runCodingSessionsAgent();
   } else if (command === "coding-sessions-status") {
@@ -1412,6 +1431,7 @@ async function runWriteMessagesConfig() {
     apiUrl: trimTrailingSlash(requiredConfigString(input.apiUrl, "apiUrl")),
     userId: requiredConfigString(input.userId, "userId"),
     agentToken: requiredConfigString(input.agentToken, "agentToken"),
+    handle: optionalString(input.handle),
     backfillDays: parseBackfillDays(input.backfillDays, null),
     allowedChatIds: input.allowedChatIds,
     selectedChats: Array.isArray(input.selectedChats) ? input.selectedChats : [],
@@ -1419,6 +1439,20 @@ async function runWriteMessagesConfig() {
   console.log(JSON.stringify({ configPath }, null, 2));
 }
 
+async function runWriteCodingSessionsConfig() {
+  const input = await readJsonInput();
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("write-coding-sessions-config expects a JSON object on stdin.");
+  }
+  const configPath = await writeCodingSessionsConfig({
+    apiUrl: trimTrailingSlash(requiredConfigString(input.apiUrl, "apiUrl")),
+    userId: requiredConfigString(input.userId, "userId"),
+    agentToken: requiredConfigString(input.agentToken, "agentToken"),
+    intervalSeconds: Number(input.intervalSeconds ?? args["coding-sessions-interval-seconds"] ?? 60),
+  });
+  console.log(JSON.stringify({ configPath }, null, 2));
+}
+
 async function runInstallMessagesAgent() {
   const configPath = stringArg("config");
   if (!configPath) throw new Error("install-messages-agent requires --config <path>");
@@ -1444,6 +1478,31 @@ async function runInstallMessagesAgent() {
   console.log(JSON.stringify(install, null, 2));
 }
 
+async function runInstallCodingSessionsAgent() {
+  const configPath = stringArg("config");
+  if (!configPath) throw new Error("install-coding-sessions-agent requires --config <path>");
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, "utf8"));
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err) throw err;
+    throw new Error(`install-coding-sessions-agent: config file at ${configPath} does not contain valid JSON.`);
+  }
+  const userId = stringArg("user-id") ?? requiredConfigString(config.userId, "userId");
+  const overrides = {
+    programArguments: parseJsonArrayArg("program"),
+    environment: parseJsonObjectArg("env"),
+  };
+
+  if (args["dry-run"]) {
+    console.log(JSON.stringify(buildCodingSessionsAgentInstall(configPath, userId, overrides), null, 2));
+    return;
+  }
+
+  const install = await installCodingSessionsAgent(configPath, userId, overrides);
+  console.log(JSON.stringify(install, null, 2));
+}
+
 async function readJsonInput() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -1932,7 +1991,7 @@ Options:
     return;
   }
 
-  if (which === "write-agent-state" || which === "write-messages-config" || which === "install-messages-agent") {
+  if (which === "write-agent-state" || which === "write-messages-config" || which === "install-messages-agent" || which === "write-coding-sessions-config" || which === "install-coding-sessions-agent") {
     console.log(`Shepherd onboarding engine commands
 
 These non-interactive commands are used by GUI onboarding apps (for example the
@@ -1944,9 +2003,12 @@ Usage:
   shepherd-onboard write-messages-config        JSON object on stdin ({apiUrl, userId, agentToken, backfillDays?, allowedChatIds, selectedChats?}) is written to ~/.shepherd/raw-messages/<userId>.json. Prints {configPath}.
   shepherd-onboard install-messages-agent --config <path>
                                                 Installs and verifies the Messages launchd agent for an existing config. Prints install metadata.
+  shepherd-onboard write-coding-sessions-config JSON object on stdin ({apiUrl, userId, agentToken, intervalSeconds?}) is written to ~/.shepherd/coding-sessions/<userId>.json. Prints {configPath}.
+  shepherd-onboard install-coding-sessions-agent --config <path>
+                                                Installs and verifies the Coding Sessions launchd agent for an existing config. Prints install metadata.
 
-install-messages-agent options:
-  --config <path>            Messages agent config created by onboarding. Required.
+install agent options:
+  --config <path>            Agent config created by onboarding. Required.
   --user-id <id>             Override the user ID. Defaults to the config's userId.
   --program <json_array>     Replace the default npx launcher with custom ProgramArguments (e.g. a signed app binary). --config <path> is appended.
   --env <json_object>        Extra EnvironmentVariables merged into the launchd plist (e.g. ELECTRON_RUN_AS_NODE).
@@ -2294,23 +2356,6 @@ function selectedSources() {
   return selected;
 }
 
-function sourceSelectionFromSession(response, fallback) {
-  const raw = response?.sources;
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    return fallback ? { ...fallback } : null;
-  }
-  return {
-    google: raw.google === true,
-    slack: raw.slack === true,
-    github: raw.github === true,
-    granola: raw.granola === true,
-    messages: raw.messages === true,
-    discord: raw.discord === true,
-    instagram: raw.instagram === true,
-    codingSessions: raw.codingSessions === true,
-  };
-}
-
 function sourceSelectionFromList(value) {
   const selected = {
     google: false,
@@ -2927,6 +2972,7 @@ async function writeMessagesConfig(input) {
       apiUrl: input.apiUrl,
       userId: input.userId,
       agentToken: input.agentToken,
+      ...(input.handle ? { handle: input.handle } : {}),
       backfillDays: input.backfillDays,
       allChats,
       allowedChatIds: allChats ? [] : allowedChatIds,
@@ -3057,22 +3103,29 @@ async function writeCodingSessionsConfig(input) {
   return path;
 }
 
-async function installCodingSessionsAgent(configPath, userId) {
-  if (platform() !== "darwin") {
-    throw new Error("automatic local coding-session sync is only supported on macOS");
-  }
-
+function buildCodingSessionsAgentInstall(configPath, userId, overrides = {}) {
   const safeId = safeFileId(userId);
   const label = `ai.shepherd.coding-sessions.${safeId}`;
   const rawDir = join(homedir(), ".shepherd", "coding-sessions");
   const agentsDir = join(homedir(), "Library", "LaunchAgents");
-  await mkdir(rawDir, { recursive: true });
-  await mkdir(agentsDir, { recursive: true });
-
   const plistPath = join(agentsDir, `${label}.plist`);
   const stdoutPath = join(rawDir, `${safeId}.out.log`);
   const stderrPath = join(rawDir, `${safeId}.err.log`);
-  const launchPath = launchAgentPath();
+  const programPrefix = Array.isArray(overrides.programArguments) && overrides.programArguments.length > 0
+    ? overrides.programArguments
+    : ["/usr/bin/env", "npx", "-y", PACKAGE_SPEC, "coding-sessions-agent"];
+  const programArguments = [...programPrefix, "--config", configPath];
+  const environment = {
+    PATH: launchAgentPath(),
+    ...stringRecord(overrides.environment),
+  };
+
+  const programArgumentsXml = programArguments
+    .map((value) => `    <string>${xmlEscape(value)}</string>`)
+    .join("\n");
+  const environmentXml = Object.entries(environment)
+    .map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`)
+    .join("\n");
 
   const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -3082,39 +3135,50 @@ async function installCodingSessionsAgent(configPath, userId) {
   <string>${xmlEscape(label)}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>/usr/bin/env</string>
-    <string>npx</string>
-    <string>-y</string>
-    <string>${PACKAGE_SPEC}</string>
-    <string>coding-sessions-agent</string>
-    <string>--config</string>
-    <string>${xmlEscape(configPath)}</string>
+${programArgumentsXml}
   </array>
   <key>KeepAlive</key>
   <true/>
   <key>RunAtLoad</key>
   <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(rawDir)}</string>
   <key>StandardOutPath</key>
   <string>${xmlEscape(stdoutPath)}</string>
   <key>StandardErrorPath</key>
   <string>${xmlEscape(stderrPath)}</string>
   <key>EnvironmentVariables</key>
   <dict>
-    <key>PATH</key>
-    <string>${xmlEscape(launchPath)}</string>
+${environmentXml}
   </dict>
 </dict>
 </plist>
 `;
 
+  return { label, rawDir, agentsDir, plistPath, stdoutPath, stderrPath, programArguments, environment, plist };
+}
+
+async function installCodingSessionsAgent(configPath, userId, overrides = {}) {
+  if (platform() !== "darwin") {
+    throw new Error("automatic local coding-session sync is only supported on macOS");
+  }
+
+  const install = buildCodingSessionsAgentInstall(configPath, userId, overrides);
+  const { label, rawDir, agentsDir, plistPath, stdoutPath, stderrPath, plist } = install;
+  await mkdir(rawDir, { recursive: true });
+  await mkdir(agentsDir, { recursive: true });
+
   await writeFile(plistPath, plist, { mode: 0o600 });
+  await chmod(plistPath, 0o600);
   const stdoutOffset = await fileLength(stdoutPath);
   const stderrOffset = await fileLength(stderrPath);
   await execFileQuiet("launchctl", ["unload", plistPath], { ignoreError: true });
   await execFileQuiet("launchctl", ["load", plistPath]);
   await execFileQuiet("launchctl", ["start", label], { ignoreError: true });
   await verifyCodingSessionsAgentLaunch({ label, stdoutPath, stderrPath, stdoutOffset, stderrOffset });
-  return { label, plistPath, stdoutPath, stderrPath };
+  return install;
 }
 
 async function verifyCodingSessionsAgentLaunch({ label, stdoutPath, stderrPath, stdoutOffset, stderrOffset }) {
@@ -4249,10 +4313,19 @@ function messageIdentity(msg) {
 }
 
 function messageState(msg) {
+  const participant = messageParticipant(msg);
   return {
     text: msg?.text ?? null,
+    chatId: msg?.chatId ?? null,
+    chatKind: messageChatKind(msg),
+    participant,
+    isFromMe: Boolean(msg?.isFromMe),
     editedAt: isoDate(msg?.editedAt),
     retractedAt: isoDate(msg?.retractedAt),
+    replyToMessageId: msg?.replyToMessageId ?? null,
+    threadRootMessageId: msg?.threadRootMessageId ?? null,
+    affectedParticipant: msg?.affectedParticipant ?? null,
+    kind: msg?.kind ?? null,
     hasAttachments: Boolean(msg?.hasAttachments ?? (Array.isArray(msg?.attachments) && msg.attachments.length > 0)),
     attachments: messageAttachmentState(msg),
   };
@@ -4260,8 +4333,16 @@ function messageState(msg) {
 
 function sameMessageState(a, b) {
   return a.text === b.text
+    && a.chatId === b.chatId
+    && a.chatKind === b.chatKind
+    && a.participant === b.participant
+    && a.isFromMe === b.isFromMe
     && a.editedAt === b.editedAt
     && a.retractedAt === b.retractedAt
+    && a.replyToMessageId === b.replyToMessageId
+    && a.threadRootMessageId === b.threadRootMessageId
+    && a.affectedParticipant === b.affectedParticipant
+    && a.kind === b.kind
     && a.hasAttachments === b.hasAttachments
     && stableLocalJson(a.attachments) === stableLocalJson(b.attachments);
 }
@@ -4699,7 +4780,7 @@ function startMessagesContactSync(sender, contactLookup, opts = {}) {
   const observeMessages = (messages) => {
     let changed = false;
     for (const msg of messages ?? []) {
-      if (rememberObservedHandle(observedHandles, contactLookup, msg?.participant)) changed = true;
+      if (rememberObservedHandle(observedHandles, contactLookup, messageParticipant(msg))) changed = true;
       if (msg?.affectedParticipant) {
         if (rememberObservedHandle(observedHandles, contactLookup, msg.affectedParticipant)) changed = true;
       }
@@ -4784,6 +4865,8 @@ function createMessageSerializer(kit, contactLookup = emptyContactLookup()) {
     },
     serialize(msg) {
       const chatId = msg.chatId ?? "unknown";
+      const participant = messageParticipant(msg);
+      const chatKind = messageChatKind(msg);
       const attachments = Array.isArray(msg.attachments) ? msg.attachments : [];
       return {
         messageId: String(msg.id ?? msg.messageId ?? msg.rowId),
@@ -4791,9 +4874,9 @@ function createMessageSerializer(kit, contactLookup = emptyContactLookup()) {
         text: msg.text ?? null,
         service: msg.service ?? "iMessage",
         chatId,
-        chatKind: msg.chatKind ?? "unknown",
+        chatKind,
         chatName: chatNames.get(chatId) ?? null,
-        participant: msg.participant ?? null,
+        participant,
         isFromMe: Boolean(msg.isFromMe),
         createdAt: isoDate(msg.createdAt) ?? new Date().toISOString(),
         deliveredAt: isoDate(msg.deliveredAt),
@@ -4835,13 +4918,31 @@ function createMessageSerializer(kit, contactLookup = emptyContactLookup()) {
         isForwarded: Boolean(msg.isForwarded),
         affectedParticipant: msg.affectedParticipant ?? null,
         newGroupName: msg.newGroupName ?? null,
-        _resolved_name: msg.participant ? contactLookup.resolveName(msg.participant) : null,
-        _is_self_handle: msg.participant ? contactLookup.isSelfHandle(msg.participant) : false,
+        _resolved_name: participant ? contactLookup.resolveName(participant) : null,
+        _is_self_handle: participant ? contactLookup.isSelfHandle(participant) : false,
       };
     },
   };
 }
 
+function messageParticipant(msg) {
+  const explicit = typeof msg?.participant === "string" ? msg.participant.trim() : "";
+  if (explicit) return explicit;
+  if (!isDirectMessageKind(messageChatKind(msg))) return null;
+  return parseDmHandleFromChatId(msg?.chatId);
+}
+
+function messageChatKind(msg) {
+  const explicit = typeof msg?.chatKind === "string" ? msg.chatKind.trim() : "";
+  if (explicit === "direct") return "dm";
+  if (explicit) return explicit;
+  return parseDmHandleFromChatId(msg?.chatId) ? "dm" : "unknown";
+}
+
+function isDirectMessageKind(kind) {
+  return kind === "dm";
+}
+
 function buildContactLookup(opts = {}) {
   const addressBook = platform() === "darwin" ? loadContactsFromAddressBookDb() : { contacts: [], myCard: null };
   if (opts.userId) {
@@ -5975,6 +6076,10 @@ function requiredConfigString(value, label) {
   return value.trim();
 }
 
+function optionalString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
 function execFileQuiet(file, argv, opts = {}) {
   return new Promise((resolve, reject) => {
     execFile(file, argv, { windowsHide: true }, (error) => {
@@ -6040,3 +6145,10 @@ function rawErrorDetails(err) {
   if (err instanceof Error) return err.stack ?? err.message;
   return String(err);
 }
+
+export const __test = {
+  messageChatKind,
+  messageParticipant,
+  messageState,
+  sameMessageState,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askshepherd",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "description": "Customer-facing Shepherd production onboarding and MCP CLI",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   "files": [
     "assets",
     "bin",
+    "source-selection.cjs",
     "README.md"
   ],
   "engines": {

package/source-selection.cjs

@@ -0,0 +1,18 @@
+function sourceSelectionFromSession(response, fallback) {
+  const raw = response?.sources;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return fallback ? { ...fallback } : null;
+  }
+  return {
+    google: raw.google === true,
+    slack: raw.slack === true,
+    github: raw.github === true,
+    granola: raw.granola === true,
+    messages: raw.messages === true,
+    discord: raw.discord === true,
+    instagram: raw.instagram === true,
+    codingSessions: raw.codingSessions === true,
+  };
+}
+
+module.exports = { sourceSelectionFromSession };