askshepherd 0.1.39 → 0.1.40

package/bin/shepherd-onboard.js

@@ -2,7 +2,7 @@
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { constants as fsConstants, existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync } from "node:fs";
-import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+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";
@@ -12,7 +12,7 @@ import { fileURLToPath } from "node:url";
 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.37";
+const PACKAGE_VERSION = "0.1.40";
 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");
@@ -133,6 +133,12 @@ async function dispatch() {
     await runMessagesChatsCommand();
   } else if (command === "messages-agent") {
     await runMessagesAgent();
+  } else if (command === "write-agent-state") {
+    await runWriteAgentState();
+  } else if (command === "write-messages-config") {
+    await runWriteMessagesConfig();
+  } else if (command === "install-messages-agent") {
+    await runInstallMessagesAgent();
   } else if (command === "coding-sessions-agent") {
     await runCodingSessionsAgent();
   } else if (command === "coding-sessions-status") {
@@ -923,9 +929,18 @@ async function writeMcpState(state) {
   const path = mcpStatePath();
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, JSON.stringify(state, null, 2), { mode: 0o600 });
+  await chmod(path, 0o600);
   return path;
 }
 
+function sanitizeUserFileId(userId) {
+  const safeId = String(userId ?? "").replace(/[^a-zA-Z0-9._-]/g, "-");
+  if (!safeId || safeId === "." || safeId === ".." || /^\.+$/.test(safeId)) {
+    throw new Error("Onboarding returned an invalid user ID for local Messages config.");
+  }
+  return safeId;
+}
+
 function mcpStatePath() {
   return expandHomePath(stringArg("state") ?? DEFAULT_MCP_STATE_PATH);
 }
@@ -1345,6 +1360,96 @@ function renderLocalCodingSessionsStatus(status) {
   return lines;
 }
 
+async function runWriteAgentState() {
+  const input = await readJsonInput();
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("write-agent-state expects a JSON object on stdin.");
+  }
+  const previous = await readOptionalAgentState();
+  const statePath = await writeAgentState({ ...(previous ?? {}), ...input });
+  console.log(JSON.stringify({ statePath }, null, 2));
+}
+
+async function runWriteMessagesConfig() {
+  const input = await readJsonInput();
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("write-messages-config expects a JSON object on stdin.");
+  }
+  const configPath = await writeMessagesConfig({
+    apiUrl: trimTrailingSlash(requiredConfigString(input.apiUrl, "apiUrl")),
+    userId: requiredConfigString(input.userId, "userId"),
+    agentToken: requiredConfigString(input.agentToken, "agentToken"),
+    backfillDays: parseBackfillDays(input.backfillDays, null),
+    allowedChatIds: input.allowedChatIds,
+    selectedChats: Array.isArray(input.selectedChats) ? input.selectedChats : [],
+  });
+  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>");
+  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-messages-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(buildMessagesAgentInstall(configPath, userId, overrides), null, 2));
+    return;
+  }
+
+  const install = await installMessagesAgent(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);
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  if (!text) throw new Error("Expected JSON input on stdin.");
+  return JSON.parse(text);
+}
+
+function parseJsonArrayArg(name) {
+  const raw = stringArg(name);
+  if (!raw) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`--${name} must be a JSON array of strings.`);
+  }
+  if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== "string")) {
+    throw new Error(`--${name} must be a JSON array of strings.`);
+  }
+  return parsed;
+}
+
+function parseJsonObjectArg(name) {
+  const raw = stringArg(name);
+  if (!raw) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`--${name} must be a JSON object of string values.`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+    || Object.values(parsed).some((value) => typeof value !== "string")) {
+    throw new Error(`--${name} must be a JSON object of string values.`);
+  }
+  return parsed;
+}
+
 async function runMessagesChatsCommand() {
   await ensureMessagesReadPermission({ noOpen: Boolean(args["no-open"]) });
   const chats = await listRecentMessageChats({
@@ -1759,6 +1864,31 @@ Options:
     return;
   }
 
+  if (which === "write-agent-state" || which === "write-messages-config" || which === "install-messages-agent") {
+    console.log(`Shepherd onboarding engine commands
+
+These non-interactive commands are used by GUI onboarding apps (for example the
+Shepherd macOS app) so that this CLI stays the single owner of Shepherd state
+file schemas and the launchd install flow.
+
+Usage:
+  shepherd-onboard write-agent-state            JSON object on stdin is merged into ~/.shepherd/raw-onboarding-agent.json. Prints {statePath}.
+  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.
+
+install-messages-agent options:
+  --config <path>            Messages 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).
+  --dry-run                  Print the launchd plist and paths without writing or loading anything.
+  --no-permission-prompt     Fail instead of prompting when Full Disk Access is missing.
+  --help                     Show this help.
+`);
+    return;
+  }
+
   if (which === "mcp") {
     console.log(`Shepherd MCP stdio proxy
 
@@ -2149,6 +2279,9 @@ async function writeAgentState(state) {
   const path = agentStatePath();
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, JSON.stringify(state, null, 2), { mode: 0o600 });
+  // writeFile's mode only applies on creation; an existing file keeps its
+  // permissions, so enforce them on every token write.
+  await chmod(path, 0o600);
   return path;
 }
 
@@ -2660,7 +2793,11 @@ function headers(token) {
 async function writeMessagesConfig(input) {
   const dir = join(homedir(), ".shepherd", "raw-messages");
   await mkdir(dir, { recursive: true });
-  const path = join(dir, `${input.userId}.json`);
+  // The userId reaches this path from the network (server-issued session id)
+  // and, via write-messages-config, from stdin; sanitize it like the launchd
+  // label does so it can never traverse outside the raw-messages directory.
+  const safeId = sanitizeUserFileId(input.userId);
+  const path = join(dir, `${safeId}.json`);
   const allowedChatIds = parseAllowedChatIds(input.allowedChatIds);
   const allChats = selectedChatIdsIncludeAll(allowedChatIds);
   if (!allChats && allowedChatIds.length === 0) {
@@ -2681,25 +2818,34 @@ async function writeMessagesConfig(input) {
     }, null, 2),
     { mode: 0o600 },
   );
+  await chmod(path, 0o600);
   return path;
 }
 
-async function installMessagesAgent(configPath, userId) {
-  if (platform() !== "darwin") {
-    throw new Error("automatic local Messages sync is only supported on macOS");
-  }
-
+function buildMessagesAgentInstall(configPath, userId, overrides = {}) {
   const safeId = userId.replace(/[^a-zA-Z0-9.-]/g, "-");
   const label = `ai.shepherd.raw-messages.${safeId}`;
   const rawDir = join(homedir(), ".shepherd", "raw-messages");
   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, "messages-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">
@@ -2709,32 +2855,43 @@ async function installMessagesAgent(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>messages-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 installMessagesAgent(configPath, userId, overrides = {}) {
+  if (platform() !== "darwin") {
+    throw new Error("automatic local Messages sync is only supported on macOS");
+  }
+
+  const install = buildMessagesAgentInstall(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);
   while (true) {
     const stdoutOffset = await fileLength(stdoutPath);
     const stderrOffset = await fileLength(stderrPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askshepherd",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "Customer-facing Shepherd production onboarding and MCP CLI",
   "type": "module",
   "bin": {