palmier 0.1.0

package/src/commands/serve.ts

@@ -0,0 +1,224 @@
+import { execSync } from "child_process";
+import * as fs from "fs";
+import { StringCodec } from "nats";
+import { loadConfig } from "../config.js";
+import { connectNats } from "../nats-client.js";
+import { listTasks, parseTaskFile, writeTaskFile, getTaskDir } from "../task.js";
+import { installTaskTimer, removeTaskTimer, getTaskStatus } from "../systemd.js";
+import type { RpcMessage, TaskWithStatus } from "../types.js";
+
+/**
+ * Start the persistent NATS RPC handler.
+ */
+export async function serveCommand(): Promise<void> {
+  const config = loadConfig();
+  const nc = await connectNats(config);
+  const sc = StringCodec();
+
+  const subject = `user.${config.userId}.agent.${config.agentId}.rpc.*`;
+  console.log(`Subscribing to: ${subject}`);
+
+  const sub = nc.subscribe(subject);
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.log("Shutting down...");
+    sub.unsubscribe();
+    await nc.drain();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // On startup, clean up orphaned pending-hooks keys for this agent
+  try {
+    const js = nc.jetstream();
+    const kv = await js.views.kv("pending-hooks");
+    const keys = await kv.keys();
+    for await (const key of keys) {
+      if (key.startsWith(`${config.agentId}.`)) {
+        console.log(`Cleaning up orphaned hook key: ${key}`);
+        await kv.delete(key);
+      }
+    }
+  } catch (err) {
+    console.error(`Warning: could not clean up pending-hooks KV: ${err}`);
+  }
+
+  console.log("Agent serving. Waiting for RPC messages...");
+
+  for await (const msg of sub) {
+    let request: RpcMessage;
+    try {
+      request = JSON.parse(sc.decode(msg.data)) as RpcMessage;
+    } catch {
+      console.error("Failed to parse RPC message");
+      if (msg.reply) {
+        msg.respond(sc.encode(JSON.stringify({ error: "Invalid JSON" })));
+      }
+      continue;
+    }
+
+    console.log(`RPC: ${request.method}`);
+
+    let response: unknown;
+    try {
+      response = await handleRpc(request);
+    } catch (err) {
+      console.error(`RPC error (${request.method}):`, err);
+      response = { error: String(err) };
+    }
+
+    if (msg.reply) {
+      msg.respond(sc.encode(JSON.stringify(response)));
+    }
+  }
+
+  async function handleRpc(request: RpcMessage): Promise<unknown> {
+    switch (request.method) {
+      case "task.list": {
+        const tasks = listTasks(config.projectRoot);
+        const tasksWithStatus: TaskWithStatus[] = tasks.map((task) => ({
+          ...task,
+          status: getTaskStatus(task.frontmatter.id),
+        }));
+        return { tasks: tasksWithStatus };
+      }
+
+      case "task.create": {
+        const params = request.params as {
+          id: string;
+          name: string;
+          user_prompt: string;
+          triggers: Array<{ type: "cron" | "once"; value: string }>;
+          requires_confirmation: boolean;
+          suppress_permissions: boolean;
+          enabled: boolean;
+          body: string;
+        };
+
+        const taskDir = getTaskDir(config.projectRoot, params.id);
+        const task = {
+          frontmatter: {
+            id: params.id,
+            name: params.name,
+            user_prompt: params.user_prompt,
+            triggers: params.triggers || [],
+            requires_confirmation: params.requires_confirmation ?? true,
+            suppress_permissions: params.suppress_permissions ?? false,
+            enabled: params.enabled ?? true,
+          },
+          body: params.body || "",
+        };
+
+        writeTaskFile(taskDir, task);
+        installTaskTimer(config, task);
+
+        return { ok: true, task_id: params.id };
+      }
+
+      case "task.update": {
+        const params = request.params as {
+          id: string;
+          name?: string;
+          user_prompt?: string;
+          triggers?: Array<{ type: "cron" | "once"; value: string }>;
+          requires_confirmation?: boolean;
+          suppress_permissions?: boolean;
+          enabled?: boolean;
+          body?: string;
+        };
+
+        const taskDir = getTaskDir(config.projectRoot, params.id);
+        const existing = parseTaskFile(taskDir);
+
+        // Merge updates
+        if (params.name !== undefined) existing.frontmatter.name = params.name;
+        if (params.user_prompt !== undefined) existing.frontmatter.user_prompt = params.user_prompt;
+        if (params.triggers !== undefined) existing.frontmatter.triggers = params.triggers;
+        if (params.requires_confirmation !== undefined)
+          existing.frontmatter.requires_confirmation = params.requires_confirmation;
+        if (params.suppress_permissions !== undefined)
+          existing.frontmatter.suppress_permissions = params.suppress_permissions;
+        if (params.enabled !== undefined) existing.frontmatter.enabled = params.enabled;
+        if (params.body !== undefined) existing.body = params.body;
+
+        writeTaskFile(taskDir, existing);
+
+        // Reinstall timer with updated config
+        removeTaskTimer(params.id);
+        installTaskTimer(config, existing);
+
+        return { ok: true, task_id: params.id };
+      }
+
+      case "task.delete": {
+        const params = request.params as { id: string };
+        const taskDir = getTaskDir(config.projectRoot, params.id);
+
+        removeTaskTimer(params.id);
+
+        // Remove task directory
+        if (fs.existsSync(taskDir)) {
+          fs.rmSync(taskDir, { recursive: true, force: true });
+        }
+
+        return { ok: true, task_id: params.id };
+      }
+
+      case "task.generate": {
+        const params = request.params as { prompt: string };
+
+        try {
+          const output = execSync(`claude -p "${params.prompt.replace(/"/g, '\\"')}"`, {
+            encoding: "utf-8",
+            cwd: config.projectRoot,
+            timeout: 120_000,
+          });
+          return { ok: true, output };
+        } catch (err: unknown) {
+          const error = err as { stdout?: string; stderr?: string };
+          return { error: "claude command failed", stdout: error.stdout, stderr: error.stderr };
+        }
+      }
+
+      case "task.run": {
+        const params = request.params as { id: string };
+        const serviceName = `palmier-task-${params.id}.service`;
+
+        try {
+          execSync(`systemctl --user start ${serviceName}`, { stdio: "inherit" });
+          return { ok: true, task_id: params.id };
+        } catch (err) {
+          return { error: `Failed to start task service: ${err}` };
+        }
+      }
+
+      case "task.status": {
+        const params = request.params as { id: string };
+        const status = getTaskStatus(params.id);
+        return { task_id: params.id, status };
+      }
+
+      case "task.logs": {
+        const params = request.params as { id: string };
+        const serviceName = `palmier-task-${params.id}.service`;
+
+        try {
+          const logs = execSync(
+            `journalctl --user -u ${serviceName} -n 100 --no-pager`,
+            { encoding: "utf-8" }
+          );
+          return { task_id: params.id, logs };
+        } catch (err: unknown) {
+          const error = err as { stdout?: string; stderr?: string };
+          return { task_id: params.id, logs: error.stdout || "", error: error.stderr };
+        }
+      }
+
+      default:
+        return { error: `Unknown method: ${request.method}` };
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,40 @@
+import * as fs from "fs";
+import * as path from "path";
+import { homedir } from "os";
+import type { AgentConfig } from "./types.js";
+
+const CONFIG_DIR = path.join(homedir(), ".config", "palmier");
+const CONFIG_FILE = path.join(CONFIG_DIR, "agent.json");
+
+/**
+ * Load agent configuration from ~/.config/palmier/agent.json.
+ * Throws if the file is missing or invalid.
+ */
+export function loadConfig(): AgentConfig {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    throw new Error(
+      "Agent not provisioned. Run `palmier init --token <token>` first.\n" +
+        `Expected config at: ${CONFIG_FILE}`
+    );
+  }
+
+  const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+  const config = JSON.parse(raw) as AgentConfig;
+
+  if (!config.agentId || !config.natsUrl || !config.natsToken) {
+    throw new Error("Invalid agent config: missing required fields (agentId, natsUrl, natsToken)");
+  }
+
+  return config;
+}
+
+/**
+ * Persist agent configuration to ~/.config/palmier/agent.json.
+ * Creates parent directories if needed.
+ */
+export function saveConfig(config: AgentConfig): void {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+}
+
+export { CONFIG_DIR, CONFIG_FILE };

package/src/index.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import "dotenv/config";
+import { Command } from "commander";
+import { initCommand } from "./commands/init.js";
+import { runCommand } from "./commands/run.js";
+import { hookCommand } from "./commands/hook.js";
+import { serveCommand } from "./commands/serve.js";
+
+const program = new Command();
+
+program
+  .name("palmier")
+  .description("Palmier agent CLI")
+  .version("0.1.0");
+
+program
+  .command("init")
+  .description("Provision this agent with a provisioning token")
+  .requiredOption("--token <token>", "Provisioning token from palmier dashboard")
+  .action(async (options: { token: string }) => {
+    await initCommand({ token: options.token });
+  });
+
+program
+  .command("run <task-id>")
+  .description("Execute a task by ID")
+  .action(async (taskId: string) => {
+    await runCommand(taskId);
+  });
+
+program
+  .command("hook")
+  .description("Handle a Claude Code hook event (reads from stdin)")
+  .action(async () => {
+    await hookCommand();
+  });
+
+program
+  .command("serve", { isDefault: true })
+  .description("Start the persistent NATS RPC handler")
+  .action(async () => {
+    await serveCommand();
+  });
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/nats-client.ts

@@ -0,0 +1,15 @@
+import { connect, type NatsConnection } from "nats";
+import type { AgentConfig } from "./types.js";
+
+/**
+ * Connect to NATS using the agent config's TCP URL and token auth.
+ */
+export async function connectNats(config: AgentConfig): Promise<NatsConnection> {
+  const nc = await connect({
+    servers: config.natsUrl,
+    token: config.natsToken,
+  });
+
+  console.log(`Connected to NATS at ${config.natsUrl}`);
+  return nc;
+}

package/src/systemd.ts

@@ -0,0 +1,232 @@
+import * as fs from "fs";
+import * as path from "path";
+import { homedir } from "os";
+import { execSync } from "child_process";
+import type { AgentConfig } from "./types.js";
+import type { ParsedTask, TaskStatus } from "./types.js";
+
+const UNIT_DIR = path.join(homedir(), ".config", "systemd", "user");
+
+function getTimerName(taskId: string): string {
+  return `palmier-task-${taskId}.timer`;
+}
+
+function getServiceName(taskId: string): string {
+  return `palmier-task-${taskId}.service`;
+}
+
+/**
+ * Convert a cron expression (5-field) to a systemd OnCalendar string.
+ * Handles basic cron patterns: minute hour day-of-month month day-of-week
+ */
+export function cronToOnCalendar(cron: string): string {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression (expected 5 fields): ${cron}`);
+  }
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+
+  // Map cron day-of-week names/numbers to systemd abbreviated names
+  const dowMap: Record<string, string> = {
+    "0": "Sun",
+    "1": "Mon",
+    "2": "Tue",
+    "3": "Wed",
+    "4": "Thu",
+    "5": "Fri",
+    "6": "Sat",
+    "7": "Sun",
+  };
+
+  // Convert day-of-week
+  let dow = dayOfWeek === "*" ? "*" : dayOfWeek;
+  if (dowMap[dow]) {
+    dow = dowMap[dow];
+  }
+
+  // Build OnCalendar string
+  // Format: DayOfWeek Year-Month-Day Hour:Minute:Second
+  const monthPart = month === "*" ? "*" : month.padStart(2, "0");
+  const dayPart = dayOfMonth === "*" ? "*" : dayOfMonth.padStart(2, "0");
+  const hourPart = hour === "*" ? "*" : hour.padStart(2, "0");
+  const minutePart = minute === "*" ? "*" : minute.padStart(2, "0");
+
+  if (dow === "*") {
+    return `*-${monthPart}-${dayPart} ${hourPart}:${minutePart}:00`;
+  }
+
+  return `${dow} *-${monthPart}-${dayPart} ${hourPart}:${minutePart}:00`;
+}
+
+/**
+ * Install a systemd user timer + service for a task.
+ */
+export function installTaskTimer(config: AgentConfig, task: ParsedTask): void {
+  fs.mkdirSync(UNIT_DIR, { recursive: true });
+
+  const taskId = task.frontmatter.id;
+  const serviceName = getServiceName(taskId);
+  const timerName = getTimerName(taskId);
+
+  // Determine the palmier binary path
+  const palmierBin = process.argv[1] || "palmier";
+
+  // Generate service unit
+  const serviceContent = `[Unit]
+Description=Palmier Task: ${task.frontmatter.name || taskId}
+
+[Service]
+Type=oneshot
+ExecStart=${palmierBin} run ${taskId}
+WorkingDirectory=${config.projectRoot}
+Environment=PATH=${process.env.PATH || "/usr/local/bin:/usr/bin:/bin"}
+`;
+
+  // Generate timer unit with OnCalendar entries for each cron trigger
+  const onCalendarLines: string[] = [];
+  for (const trigger of task.frontmatter.triggers || []) {
+    if (trigger.type === "cron") {
+      onCalendarLines.push(`OnCalendar=${cronToOnCalendar(trigger.value)}`);
+    } else if (trigger.type === "once") {
+      // "once" triggers use OnActiveSec or a specific timestamp
+      onCalendarLines.push(`OnActiveSec=${trigger.value}`);
+    }
+  }
+
+  const timerContent = `[Unit]
+Description=Timer for Palmier Task: ${task.frontmatter.name || taskId}
+
+[Timer]
+${onCalendarLines.join("\n")}
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`;
+
+  // Write unit files
+  fs.writeFileSync(path.join(UNIT_DIR, serviceName), serviceContent, "utf-8");
+  fs.writeFileSync(path.join(UNIT_DIR, timerName), timerContent, "utf-8");
+
+  // Reload and enable
+  daemonReload();
+
+  if (task.frontmatter.enabled) {
+    execSync(`systemctl --user enable --now ${timerName}`, { stdio: "inherit" });
+  } else {
+    execSync(`systemctl --user enable ${timerName}`, { stdio: "inherit" });
+  }
+}
+
+/**
+ * Remove a task's systemd timer and service files.
+ */
+export function removeTaskTimer(taskId: string): void {
+  const timerName = getTimerName(taskId);
+  const serviceName = getServiceName(taskId);
+
+  // Stop and disable
+  try {
+    execSync(`systemctl --user stop ${timerName}`, { stdio: "inherit" });
+  } catch {
+    // Timer might not be running
+  }
+
+  try {
+    execSync(`systemctl --user disable ${timerName}`, { stdio: "inherit" });
+  } catch {
+    // Timer might not be enabled
+  }
+
+  // Remove unit files
+  const timerPath = path.join(UNIT_DIR, timerName);
+  const servicePath = path.join(UNIT_DIR, serviceName);
+
+  if (fs.existsSync(timerPath)) fs.unlinkSync(timerPath);
+  if (fs.existsSync(servicePath)) fs.unlinkSync(servicePath);
+
+  daemonReload();
+}
+
+/**
+ * Query systemd for task status information.
+ */
+export function getTaskStatus(taskId: string): TaskStatus {
+  const timerName = getTimerName(taskId);
+  const serviceName = getServiceName(taskId);
+
+  let state: TaskStatus["state"] = "inactive";
+  let lastRun: string | undefined;
+  let lastResult: number | undefined;
+  let nextRun: string | undefined;
+
+  // Check if timer is active
+  try {
+    const activeState = execSync(`systemctl --user is-active ${timerName}`, {
+      encoding: "utf-8",
+    }).trim();
+    if (activeState === "active") {
+      state = "active";
+    }
+  } catch {
+    // Not active
+  }
+
+  // Check if service has failed
+  try {
+    const serviceState = execSync(`systemctl --user is-failed ${serviceName}`, {
+      encoding: "utf-8",
+    }).trim();
+    if (serviceState === "failed") {
+      state = "failed";
+    }
+  } catch {
+    // Not failed
+  }
+
+  // Get last run time and result
+  try {
+    const props = execSync(
+      `systemctl --user show ${serviceName} --property=ExecMainStartTimestamp,ExecMainStatus`,
+      { encoding: "utf-8" }
+    );
+    for (const line of props.split("\n")) {
+      if (line.startsWith("ExecMainStartTimestamp=") && line.trim() !== "ExecMainStartTimestamp=") {
+        const val = line.split("=", 2)[1].trim();
+        if (val) lastRun = val;
+      }
+      if (line.startsWith("ExecMainStatus=")) {
+        const val = parseInt(line.split("=", 2)[1].trim(), 10);
+        if (!isNaN(val)) lastResult = val;
+      }
+    }
+  } catch {
+    // Couldn't get properties
+  }
+
+  // Get next run time from timer
+  try {
+    const timerProps = execSync(
+      `systemctl --user show ${timerName} --property=NextElapseUSecRealtime`,
+      { encoding: "utf-8" }
+    );
+    for (const line of timerProps.split("\n")) {
+      if (line.startsWith("NextElapseUSecRealtime=")) {
+        const val = line.split("=", 2)[1].trim();
+        if (val) nextRun = val;
+      }
+    }
+  } catch {
+    // Couldn't get next run
+  }
+
+  return { state, lastRun, lastResult, nextRun };
+}
+
+/**
+ * Run systemctl --user daemon-reload.
+ */
+export function daemonReload(): void {
+  execSync("systemctl --user daemon-reload", { stdio: "inherit" });
+}

package/src/task.ts

@@ -0,0 +1,91 @@
+import * as fs from "fs";
+import * as path from "path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import type { ParsedTask, TaskFrontmatter } from "./types.js";
+
+/**
+ * Parse a TASK.md file from the given task directory.
+ */
+export function parseTaskFile(taskDir: string): ParsedTask {
+  const filePath = path.join(taskDir, "TASK.md");
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`TASK.md not found at: ${filePath}`);
+  }
+
+  const content = fs.readFileSync(filePath, "utf-8");
+  return parseTaskContent(content);
+}
+
+/**
+ * Parse TASK.md content string into frontmatter + body.
+ */
+function parseTaskContent(content: string): ParsedTask {
+  const fmRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+  const match = content.match(fmRegex);
+
+  if (!match) {
+    throw new Error("TASK.md is missing valid YAML frontmatter delimiters (---)");
+  }
+
+  const frontmatter = parseYaml(match[1]) as TaskFrontmatter;
+  const body = (match[2] || "").trim();
+
+  if (!frontmatter.id) {
+    throw new Error("TASK.md frontmatter must include at least: id");
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Write a TASK.md file to the given task directory.
+ * Creates the directory if it doesn't exist.
+ */
+export function writeTaskFile(taskDir: string, task: ParsedTask): void {
+  fs.mkdirSync(taskDir, { recursive: true });
+
+  const yamlStr = stringifyYaml(task.frontmatter).trim();
+  const content = `---\n${yamlStr}\n---\n${task.body}\n`;
+
+  const filePath = path.join(taskDir, "TASK.md");
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+
+/**
+ * List all tasks from projectRoot/tasks/{id}/TASK.md.
+ */
+export function listTasks(projectRoot: string): ParsedTask[] {
+  const tasksDir = path.join(projectRoot, "tasks");
+
+  if (!fs.existsSync(tasksDir)) {
+    return [];
+  }
+
+  const entries = fs.readdirSync(tasksDir, { withFileTypes: true });
+  const tasks: ParsedTask[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const taskDir = path.join(tasksDir, entry.name);
+    const taskFile = path.join(taskDir, "TASK.md");
+
+    if (!fs.existsSync(taskFile)) continue;
+
+    try {
+      tasks.push(parseTaskFile(taskDir));
+    } catch (err) {
+      console.error(`Warning: failed to parse task in ${taskDir}: ${err}`);
+    }
+  }
+
+  return tasks;
+}
+
+/**
+ * Get the directory path for a task by its ID.
+ */
+export function getTaskDir(projectRoot: string, taskId: string): string {
+  return path.join(projectRoot, "tasks", taskId);
+}