@cursor/july 0.1.1

package/src/internal/cli-slack.ts

@@ -0,0 +1,175 @@
+/**
+ * `agent-serve slack …` CLI — manifests, setup, doctor (Socket Mode).
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join, resolve as resolvePath } from "node:path";
+import {
+  buildSlackManifestPair,
+  formatSlackSetupGuide,
+  initSlackChannel,
+  runSlackDoctor,
+} from "../channels/slack/index.js";
+
+export interface SlackCliOptions {
+  dir: string;
+  name?: string;
+  env?: "dev" | "prod" | "both";
+  json?: boolean;
+  print?: boolean;
+  /** Per-agent env prefix for tokens (`MY_AGENT`). */
+  prefix?: string;
+  /** Use shared `SLACK_*` env vars (no per-agent prefix). */
+  noPrefix?: boolean;
+  /** Subscribe manifests to channel-post events (opt-in channel watch). */
+  channelPosts?: boolean;
+}
+
+const SLACK_HELP = `agent-serve slack — Slack channel pack helpers (Socket Mode)
+
+Usage:
+  agent-serve slack setup
+  agent-serve slack init      [--dir .] [--name NAME] [--prefix PREFIX | --no-prefix]
+                                [--channel-posts]
+  agent-serve slack manifest --env dev|prod|both [--dir .] [--name NAME]
+                                [--print]
+  agent-serve slack doctor [--prefix PREFIX] [--json]
+
+Env tokens:
+  single agent:  SLACK_BOT_TOKEN + SLACK_APP_TOKEN
+  multi-agent:   <PREFIX>_SLACK_BOT_TOKEN + <PREFIX>_SLACK_APP_TOKEN
+                 (init defaults PREFIX from the directory name)
+
+See also: skills/setup-slack/SKILL.md
+`;
+
+export async function cmdSlack(
+  subcommand: string | undefined,
+  options: SlackCliOptions
+): Promise<number> {
+  switch (subcommand) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(SLACK_HELP);
+      return subcommand === undefined ? 1 : 0;
+    case "setup":
+      process.stdout.write(formatSlackSetupGuide());
+      return 0;
+    case "init":
+      return cmdSlackInit(options);
+    case "manifest":
+      return runManifest(options);
+    case "doctor":
+      return runDoctor(options);
+    default:
+      process.stderr.write(`Unknown slack subcommand: ${subcommand}\n`);
+      process.stdout.write(SLACK_HELP);
+      return 1;
+  }
+}
+
+async function cmdSlackInit(options: SlackCliOptions): Promise<number> {
+  const dir = resolvePath(options.dir);
+  try {
+    const result = await initSlackChannel({
+      dir,
+      ...(options.name === undefined ? {} : { name: options.name }),
+      ...(options.noPrefix === true
+        ? { envPrefix: "" }
+        : options.prefix === undefined
+          ? {}
+          : { envPrefix: options.prefix }),
+      ...(options.channelPosts === true ? { channelPosts: true } : {}),
+    });
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          directory: result.rootDir,
+          created: result.files,
+          envPrefix: result.envPrefix ?? null,
+          envKeys: result.envKeys,
+          next: [
+            "Open https://api.slack.com/apps → Create from manifest",
+            "Import .agent-serve/slack/manifest.dev.json (then prod)",
+            `Install apps; set ${result.envKeys.bot} + ${result.envKeys.app}`,
+            result.envPrefix === undefined
+              ? "agent-serve slack doctor"
+              : `agent-serve slack doctor --prefix ${result.envPrefix}`,
+            "agent-serve serve --dir . --dev",
+            "agent-serve slack setup",
+          ],
+        },
+        null,
+        2
+      )}\n`
+    );
+    return 0;
+  } catch (error) {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`
+    );
+    return 1;
+  }
+}
+
+async function runManifest(options: SlackCliOptions): Promise<number> {
+  const env = options.env ?? "both";
+  const dir = resolvePath(options.dir);
+  const name = options.name ?? basename(dir);
+  const pair = buildSlackManifestPair({
+    name,
+    ...(options.channelPosts === true ? { channelPosts: true } : {}),
+  });
+
+  if (options.print) {
+    if (env === "dev" || env === "both") {
+      process.stdout.write(`${JSON.stringify(pair.dev, null, 2)}\n`);
+    }
+    if (env === "prod" || env === "both") {
+      if (env === "both") {
+        process.stdout.write("--- prod ---\n");
+      }
+      process.stdout.write(`${JSON.stringify(pair.prod, null, 2)}\n`);
+    }
+    return 0;
+  }
+
+  const outDir = join(dir, ".agent-serve/slack");
+  await mkdir(outDir, { recursive: true });
+  const written: string[] = [];
+  if (env === "dev" || env === "both") {
+    const path = join(outDir, "manifest.dev.json");
+    await writeFile(path, `${JSON.stringify(pair.dev, null, 2)}\n`);
+    written.push(path);
+  }
+  if (env === "prod" || env === "both") {
+    const path = join(outDir, "manifest.prod.json");
+    await writeFile(path, `${JSON.stringify(pair.prod, null, 2)}\n`);
+    written.push(path);
+  }
+  process.stdout.write(`${JSON.stringify({ ok: true, written }, null, 2)}\n`);
+  return 0;
+}
+
+async function runDoctor(options: SlackCliOptions): Promise<number> {
+  const result = await runSlackDoctor(
+    options.prefix === undefined ? {} : { envPrefix: options.prefix }
+  );
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(
+      `env: ${result.envKeys.bot} / ${result.envKeys.app}\n`
+    );
+    for (const check of result.checks) {
+      process.stdout.write(
+        `${check.ok ? "ok" : "!!"}  ${check.id}: ${check.message}\n`
+      );
+    }
+    process.stdout.write(result.ok ? "doctor: pass\n" : "doctor: fail\n");
+  }
+  return result.ok ? 0 : 1;
+}

package/src/internal/cloud-merge.ts

@@ -0,0 +1,41 @@
+import type { AgentCloudOptions, AgentRuntime } from "../types.js";
+
+/**
+ * Merge a per-session cloud override over the agent's static cloud config.
+ *
+ * Session-scoped `repos` / `env` / scalar flags win (so a channel can point
+ * a cloud agent at a specific PR per session), and `envVars` are deep-merged
+ * with the override taking precedence per key. Returns the defined side when
+ * only one is present. Named fields keep base/override precedence explicit
+ * at every call site.
+ */
+export function mergeCloudOptions(args: {
+  base: AgentCloudOptions | undefined;
+  override: AgentCloudOptions | undefined;
+}): AgentCloudOptions | undefined {
+  const { base, override } = args;
+  if (base === undefined) {
+    return override;
+  }
+  if (override === undefined) {
+    return base;
+  }
+  return {
+    ...base,
+    ...override,
+    ...(base.envVars !== undefined || override.envVars !== undefined
+      ? { envVars: { ...base.envVars, ...override.envVars } }
+      : {}),
+  };
+}
+
+/**
+ * Session turn runtime: a per-session `cloud` attach forces cloud even when
+ * the agent defaults to local (chat server tools + Drive handoff).
+ */
+export function resolveSessionRuntime(args: {
+  agentRuntime: AgentRuntime;
+  cloudOverride: AgentCloudOptions | undefined;
+}): AgentRuntime {
+  return args.cloudOverride !== undefined ? "cloud" : args.agentRuntime;
+}

package/src/internal/cron.ts

@@ -0,0 +1,78 @@
+/**
+ * Cron helpers for schedules and reminders. Thin wrapper around `croner`
+ * (same package as backend/server) so we keep a stable `parseCron` /
+ * `isValidCron` surface for discovery and runners.
+ *
+ * Standard 5-field expressions (minute hour day-of-month month day-of-week),
+ * evaluated in UTC with minute granularity.
+ */
+
+import { Cron } from "croner";
+
+export interface CronExpression {
+  readonly source: string;
+  matches(date: Date): boolean;
+  /** Next fire strictly after `after` (defaults to now). */
+  nextFire(after?: Date): Date;
+}
+
+function createCroner(source: string): Cron {
+  try {
+    return new Cron(source, {
+      timezone: "UTC",
+      // Schedules/reminders are 5-field; reject 6-field seconds forms.
+      legacyMode: true,
+    });
+  } catch (error) {
+    throw new Error(
+      `Invalid cron expression "${source}": ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+}
+
+/**
+ * True when `date`'s UTC minute is a fire time for the expression.
+ * Implemented via croner's nextRun from one second before the minute floor.
+ */
+function matchesCron(cron: Cron, date: Date): boolean {
+  const floorMs = Math.floor(date.getTime() / 60_000) * 60_000;
+  const next = cron.nextRun(new Date(floorMs - 1_000));
+  return next !== null && next.getTime() === floorMs;
+}
+
+export function parseCron(source: string): CronExpression {
+  const trimmed = source.trim();
+  const parts = trimmed.split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(
+      `Invalid cron expression "${source}": expected 5 fields, got ${parts.length}`
+    );
+  }
+  const cron = createCroner(trimmed);
+  return {
+    source: trimmed,
+    matches(date: Date): boolean {
+      return matchesCron(cron, date);
+    },
+    nextFire(after: Date = new Date()): Date {
+      const next = cron.nextRun(after);
+      if (next === null) {
+        throw new Error(
+          `Could not find next fire for cron "${trimmed}" after ${after.toISOString()}`
+        );
+      }
+      return next;
+    },
+  };
+}
+
+export function isValidCron(source: string): boolean {
+  try {
+    parseCron(source);
+    return true;
+  } catch {
+    return false;
+  }
+}