@relayflows/sdk 2.0.18 → 2.0.20

package/src/human-to.ts

@@ -0,0 +1,71 @@
+/**
+ * Who an `f.human(question, { to })` question is for, parsed from the
+ * author's `to` string. This is the delivery contract Cloud reads (the local
+ * kit records it, Cloud delivers it), so the forms are fixed here and
+ * documented in docs/SURFACE.md §5 Human gates:
+ *
+ *   "slack:#eng"        → post in the Slack channel; anyone there may answer
+ *   "slack:@khaliq"     → DM the Slack user; only they may answer
+ *   "github:@khaliq"    → comment on the triggering issue / pull request,
+ *                         mentioning the handle; only they may answer
+ *   "khaliq"            → the deploy's approver, on whichever channel the run
+ *                         was triggered from (Cloud resolves; the local kit
+ *                         only records it)
+ *
+ * Anything else — an unknown provider (`email:x`), a provider with no target
+ * (`slack:`), a GitHub channel (`github:#eng`), a target with whitespace or
+ * other characters no handle carries — is refused as `human_to_invalid`
+ * rather than turned into a delivery target that would silently reach no one.
+ */
+export type HumanRecipient =
+  | { readonly provider: 'slack'; readonly kind: 'channel' | 'user'; readonly target: string }
+  | { readonly provider: 'github'; readonly kind: 'user'; readonly target: string }
+  | { readonly provider: 'approver'; readonly kind: 'user'; readonly target: string };
+
+export type HumanRecipientParse =
+  | { readonly ok: true; readonly recipient: HumanRecipient }
+  | { readonly ok: false; readonly reason: string };
+
+/** A Slack channel name, or a Slack / GitHub / approver handle: one word, no spaces or quotes. */
+const TARGET = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/u;
+const PROVIDER_FORM = /^([A-Za-z][A-Za-z0-9_-]*)\s*:(.*)$/su;
+
+export function parseHumanTo(to: string): HumanRecipientParse {
+  const trimmed = to.trim();
+  if (trimmed === '') return { ok: false, reason: 'to is empty' };
+  const match = PROVIDER_FORM.exec(trimmed);
+  if (match === null) {
+    const target = trimmed.replace(/^@/u, '');
+    if (!TARGET.test(target)) return { ok: false, reason: `"${trimmed}" is not a handle (one word: letters, digits, . _ -)` };
+    return { ok: true, recipient: { provider: 'approver', kind: 'user', target } };
+  }
+  const provider = match[1]!.toLowerCase();
+  const rest = match[2]!.trim();
+  if (provider !== 'slack' && provider !== 'github') {
+    return { ok: false, reason: `"${provider}:" is not a delivery provider; use "slack:#channel", "slack:@user", "github:@user" or a bare approver handle` };
+  }
+  if (rest === '') return { ok: false, reason: `"${provider}:" names no ${provider === 'slack' ? 'channel or user' : 'user'}` };
+  if (rest.startsWith('#')) {
+    if (provider === 'github') return { ok: false, reason: `"${trimmed}": GitHub has no channels; use "github:@user"` };
+    const target = rest.slice(1);
+    if (!TARGET.test(target)) return { ok: false, reason: `"${trimmed}" is not a Slack channel name` };
+    return { ok: true, recipient: { provider: 'slack', kind: 'channel', target } };
+  }
+  const target = rest.replace(/^@/u, '');
+  if (!TARGET.test(target)) return { ok: false, reason: `"${trimmed}" is not a ${provider === 'slack' ? 'Slack' : 'GitHub'} handle` };
+  return { ok: true, recipient: { provider, kind: 'user', target } };
+}
+
+/** The parsed recipient of a `to` already accepted by `f.human` (`parseHumanTo` ok). */
+export function parseHumanRecipient(to: string): HumanRecipient {
+  const parsed = parseHumanTo(to);
+  if (!parsed.ok) throw new Error(`f.human to ${parsed.reason}`);
+  return parsed.recipient;
+}
+
+/** The Cloud integration a recipient needs connected: none for the approver, none for a malformed `to`. */
+export function humanRecipientProvider(to: string): 'slack' | 'github' | undefined {
+  const parsed = parseHumanTo(to);
+  if (!parsed.ok || parsed.recipient.provider === 'approver') return undefined;
+  return parsed.recipient.provider;
+}

package/src/index.ts

@@ -64,8 +64,10 @@ export {
   type CloudFlowSource, type RunInCloudOptions, type CloudRunReceipt, type CloudRunState,
 } from './cloud-run.js';
 export {
-  downloadCloudPatch, applyCloudPatch, packWorkingTree, patchedPaths, MAX_SYNC_BYTES,
-  type CloudPatch, type PackedTree,
+  downloadCloudPatch, downloadCloudPatchSet, applyCloudPatch, packWorkingTree, patchedPaths,
+  excludedPatchPaths, CLOUD_SYNC_PATCH_EXCLUDES, MAX_SYNC_BYTES,
+  type CloudPatch, type CloudPathPatch, type CloudPatchSet, type PackedTree,
+  type ApplyCloudPatchOptions, type AppliedCloudPatch,
 } from './cloud-sync.js';
 export {
   scheduleInCloud, listCloudSchedules, unscheduleInCloud, everyToCron, declaredScheduleCron,
@@ -84,6 +86,7 @@ export {
   flowRequirements, describeFlowRequirements, harnessFromCli, FLOW_HARNESSES,
   type FlowRequirements, type FlowRequirementsContext, type FlowIntegrationRequirement, type FlowHarnessRequirement, type FlowHarness,
 } from './flow-requirements.js';
+export { parseHumanTo, parseHumanRecipient, humanRecipientProvider, type HumanRecipient, type HumanRecipientParse } from './human-to.js';
 
 export { canonicalize, specHash } from './canonical.js';
 export {

package/src/relay-cli.ts

@@ -0,0 +1,117 @@
+import { readFileSync } from 'node:fs';
+
+import { runCli } from './cli.js';
+import { CLI_VERBS, CLI_VERB_NAMES, type CliCommandSpec } from './cli-commands.js';
+
+/**
+ * The `@relayflows/sdk/relay-cli` entrypoint: a mountable CLI surface.
+ *
+ * `agent-relay` mounts this as `agent-relay flows`. The surface is a thin
+ * projection over the CLI this package already ships -- `commands` comes from
+ * the same `CLI_VERBS` table `parseArgs` dispatches on, and `run` delegates
+ * straight to `runCli`. No command is reimplemented here, and
+ * `packages/relayflows/bin/flows.js` keeps calling `runCli` on the same path.
+ *
+ * Structurally typed against `@agent-relay/cli-surface` without importing it,
+ * so `dist/relay-cli.d.ts` has no dependency on the contract package and this
+ * package gains no runtime dependency on relay. `tests/relay-cli-surface.test.ts`
+ * asserts the assignability and runs the contract's own conformance checks.
+ */
+
+/** Host-supplied output sink. Mirrors `RelayCliIo`. */
+export interface RelayCliIo {
+  stdout(chunk: string): void;
+  stderr(chunk: string): void;
+}
+
+/** A mountable product CLI. Mirrors `RelayCliSurface`. */
+export interface RelayCliSurface {
+  id: string;
+  version: string;
+  contract: 1;
+  commands: readonly CliCommandSpec[];
+  run(argv: readonly string[], io: RelayCliIo): Promise<number>;
+}
+
+/** Options for {@link createRelayCliSurface}. */
+export interface CreateRelayCliSurfaceOptions {
+  /**
+   * Cancellation for the long-running verbs, owned by the host.
+   *
+   * A surface must install no global signal handlers, so one is always passed
+   * to `runCli` -- a never-aborting signal when the host supplies none. Pass a
+   * real one to get graceful cancellation (for example, the
+   * "Stopped observing; the hosted run has not been cancelled" path on
+   * `run --cloud --wait`) instead of the host's SIGINT killing the process.
+   */
+  signal?: AbortSignal;
+}
+
+/** Exit code for an argv the surface cannot route, per the contract. */
+const EXIT_UNKNOWN_COMMAND = 2;
+
+/** Drop `variants` -- the routing detail the host has no use for. */
+function toCommandSpec(verb: CliCommandSpec & { variants?: unknown }): CliCommandSpec {
+  const { variants: _variants, ...spec } = verb;
+  return spec;
+}
+
+/**
+ * Read this package's version from its own manifest.
+ *
+ * Resolved from `import.meta.url` rather than imported, because `package.json`
+ * sits outside `rootDir` and a hardcoded literal would silently go stale at the
+ * next release. `src/` and `dist/` are both one level below the manifest, so
+ * the same relative path is correct before and after a build.
+ */
+function packageVersion(): string {
+  try {
+    const manifest: unknown = JSON.parse(
+      readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+    );
+    const version = (manifest as { version?: unknown }).version;
+    return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
+  } catch {
+    // A surface that cannot read its own manifest is still perfectly runnable;
+    // refusing to mount over a cosmetic field would be the worse failure.
+    return '0.0.0';
+  }
+}
+
+/**
+ * Build the relayflows CLI surface.
+ *
+ * @param options - Host-supplied cancellation.
+ * @returns A surface whose `run` resolves to an exit code, writes only through
+ *   the supplied io, and installs no process signal handlers.
+ */
+export function createRelayCliSurface(
+  options: CreateRelayCliSurfaceOptions = {},
+): RelayCliSurface {
+  return {
+    id: 'relayflows',
+    version: packageVersion(),
+    contract: 1,
+    commands: CLI_VERBS.map(toCommandSpec),
+    async run(argv: readonly string[], io: RelayCliIo): Promise<number> {
+      const verb = argv[0];
+      // `runCli` would refuse this too, but with the full usage block. Naming
+      // the offending token is the more useful answer when the host has just
+      // routed `agent-relay flows <typo>` here.
+      if (verb !== undefined && !verb.startsWith('-') && !CLI_VERB_NAMES.has(verb)) {
+        io.stderr(`error: '${verb}' is not a command of relayflows\n`);
+        io.stderr("Run 'agent-relay flows --help' for the available commands.\n");
+        return EXIT_UNKNOWN_COMMAND;
+      }
+      return runCli(
+        argv,
+        // `CliIo` is line-oriented and the contract's io is chunk-oriented, so
+        // the terminator is added here rather than by every call site.
+        { stdout: (line) => io.stdout(`${line}\n`), stderr: (line) => io.stderr(`${line}\n`) },
+        // Always pass a signal: that is what keeps `runCli` from installing the
+        // SIGINT/SIGTERM handlers the standalone binary still relies on.
+        { signal: options.signal ?? new AbortController().signal },
+      );
+    },
+  };
+}