@checkstack/automation-frontend 0.2.0

package/src/editor/template-helpers.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Tests for the scope → completion-field flattening + shell-env derivation.
+ *
+ * The key invariant: completion fields carry both the canonical `path`
+ * (used ONLY for shell-env names, which must match the backend's
+ * path-based injection) and the runtime-parseable `templateRef` (what
+ * gets inserted into `{{ }}`).
+ */
+import { describe, expect, it } from "bun:test";
+import type { VariableScope } from "@checkstack/automation-common";
+import { fieldsToShellEnvVars, flattenScopeToFields } from "./template-helpers";
+
+const scope: VariableScope = {
+  entries: [
+    {
+      path: "trigger",
+      templateRef: "trigger",
+      type: "object",
+      children: [
+        {
+          path: "trigger.payload",
+          templateRef: "trigger.payload",
+          type: "object",
+          children: [
+            {
+              path: "trigger.payload.severity",
+              templateRef: "trigger.payload.severity",
+              type: "string",
+              jsonSchema: { type: "string", enum: ["low", "high"] },
+            },
+          ],
+        },
+      ],
+    },
+    {
+      path: "artifact",
+      templateRef: "artifacts",
+      type: "object",
+      children: [
+        {
+          path: "artifact.integration-jira.issue",
+          templateRef: 'artifacts["integration-jira.issue"]',
+          type: "object",
+          children: [
+            {
+              path: "artifact.integration-jira.issue.issueKey",
+              templateRef: 'artifacts["integration-jira.issue"].issueKey',
+              type: "string",
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+const arrayScope: VariableScope = {
+  entries: [
+    {
+      path: "artifact.integration-jira.issue",
+      templateRef: 'artifacts["integration-jira.issue"]',
+      type: "object",
+      children: [
+        {
+          path: "artifact.integration-jira.issue.tags",
+          templateRef: 'artifacts["integration-jira.issue"].tags',
+          type: "string[]",
+          referenceable: true,
+          children: [
+            {
+              path: "artifact.integration-jira.issue.tags[0]",
+              templateRef: 'artifacts["integration-jira.issue"].tags[0]',
+              type: "string",
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+describe("flattenScopeToFields", () => {
+  it("emits both the whole-array field and its element field", () => {
+    const fields = flattenScopeToFields(arrayScope);
+    const refs = fields.map((f) => f.templateRef);
+    // Whole array (referenceable) AND the element are both offered.
+    expect(refs).toContain('artifacts["integration-jira.issue"].tags');
+    expect(refs).toContain('artifacts["integration-jira.issue"].tags[0]');
+  });
+
+  it("derives shell env names from the canonical path for array fields", () => {
+    const fields = flattenScopeToFields(arrayScope);
+    const vars = fieldsToShellEnvVars(fields);
+    for (const v of vars) {
+      expect(v.name).toMatch(/^CHECKSTACK_/);
+      expect(v.name).not.toContain("[");
+      expect(v.name).not.toContain("]");
+      expect(v.name).not.toContain('"');
+    }
+  });
+
+  it("carries both path and templateRef on each leaf", () => {
+    const fields = flattenScopeToFields(scope);
+    const severity = fields.find(
+      (f) => f.path === "trigger.payload.severity",
+    );
+    expect(severity?.templateRef).toBe("trigger.payload.severity");
+    expect(severity?.enumValues).toEqual(["low", "high"]);
+
+    const issueKey = fields.find(
+      (f) => f.path === "artifact.integration-jira.issue.issueKey",
+    );
+    expect(issueKey?.templateRef).toBe(
+      'artifacts["integration-jira.issue"].issueKey',
+    );
+  });
+
+  it("falls back to path when an entry has no templateRef", () => {
+    const legacyScope: VariableScope = {
+      entries: [{ path: "var.foo", type: "string" }],
+    };
+    const [field] = flattenScopeToFields(legacyScope);
+    expect(field?.templateRef).toBe("var.foo");
+  });
+});
+
+describe("fieldsToShellEnvVars", () => {
+  it("derives env names from the canonical dotted path, NOT the bracket templateRef", () => {
+    const fields = flattenScopeToFields(scope);
+    const vars = fieldsToShellEnvVars(fields);
+    const names = vars.map((v) => v.name);
+
+    // Artifact env var must come from the dotted path, producing a clean
+    // CHECKSTACK_ARTIFACT_* name — never from the bracket/quote form.
+    const artifactVar = names.find((n) => n.includes("ARTIFACT"));
+    expect(artifactVar).toBeDefined();
+    expect(artifactVar).toMatch(/^CHECKSTACK_/);
+    // No bracket / quote leakage from the templateRef into the env name.
+    for (const name of names) {
+      expect(name).not.toContain("[");
+      expect(name).not.toContain('"');
+      expect(name).not.toContain("artifacts");
+    }
+  });
+});

package/src/editor/template-helpers.ts

@@ -0,0 +1,95 @@
+import type { VariableEntry, VariableScope } from "@checkstack/automation-common";
+import { toShellEnvKey } from "@checkstack/automation-common";
+import type { ShellEnvVar } from "@checkstack/ui";
+import type { CompletionField, CompletionFilter } from "./template-completion";
+
+/**
+ * Built-in template filters shipped by the engine. Mirrors the registry
+ * built in `@checkstack/template-engine` → `createDefaultFilterRegistry`.
+ * Drives the "filter" stage of staged completion (after a `|`).
+ *
+ * Hand-written rather than auto-derived so we can supply human-readable
+ * signatures + short descriptions (the engine stores only the function).
+ */
+export const TEMPLATE_FILTERS: readonly CompletionFilter[] = [
+  { name: "default", signature: "fallback", description: "Substitute when null / undefined / empty.", hasArgs: true },
+  { name: "upper", description: "Uppercase a string." },
+  { name: "lower", description: "Lowercase a string." },
+  { name: "capitalize", description: "Capitalise the first letter." },
+  { name: "trim", description: "Strip leading + trailing whitespace." },
+  { name: "truncate", signature: "length", description: "Truncate to N chars, append …", hasArgs: true },
+  { name: "length", description: "Length of a string / array / object." },
+  { name: "json", description: "Stringify a value as JSON." },
+  { name: "iso", description: "Format a date as ISO-8601." },
+  { name: "date", signature: "format", description: 'Format: "ISO" | "date" | "time" | "unix" | "rfc2822".', hasArgs: true },
+  { name: "join", signature: "separator", description: 'Join an array (default ", ").', hasArgs: true },
+  { name: "replace", signature: "search, replacement", description: "Replace every occurrence.", hasArgs: true },
+  { name: "not", description: "Negate truthiness." },
+];
+
+/**
+ * Map the in-scope completion fields to the `$CHECKSTACK_*` env vars a
+ * shell script action receives. Uses the shared {@link toShellEnvKey}
+ * rule so the `$` names suggested here are exactly the ones the backend
+ * injects at run time.
+ */
+export function fieldsToShellEnvVars(
+  fields: readonly CompletionField[],
+): ShellEnvVar[] {
+  // Derive from the canonical dotted `path`, NOT `templateRef`. The
+  // backend's `toShellEnvKey` injection is path-based, so deriving from
+  // `path` keeps the `$CHECKSTACK_*` names suggested here byte-identical
+  // to what the runtime injects (bracket-notation templateRefs would
+  // produce different — and wrong — env var names).
+  return fields.map((field) => ({
+    name: toShellEnvKey(field.path),
+    description: field.type ? `${field.path} (${field.type})` : field.path,
+  }));
+}
+
+/**
+ * Flatten a resolved `VariableScope` to the fields the completion
+ * provider offers in its "field" stage. Object-typed parents are
+ * skipped — operators interpolate leaf values, not whole objects — but
+ * `referenceable` nodes (arrays) are emitted alongside their element
+ * children so both `{{ ...tags }}` and `{{ ...tags[0] }}` are offered.
+ * Each field carries its `enumValues` (when the schema declared an
+ * `enum`) so the provider's "value" stage can suggest concrete
+ * comparisons.
+ */
+export function flattenScopeToFields(scope: VariableScope): CompletionField[] {
+  const out: CompletionField[] = [];
+  const visit = (entries: readonly VariableEntry[]): void => {
+    for (const entry of entries) {
+      // Emit a field for every leaf, plus any node explicitly flagged
+      // `referenceable` (arrays — both the whole array and its elements are
+      // insertable). Always recurse into children regardless.
+      if (!entry.children?.length || entry.referenceable) {
+        out.push({
+          path: entry.path,
+          templateRef: entry.templateRef ?? entry.path,
+          type: entry.type,
+          description: entry.description,
+          enumValues: extractEnum(entry.jsonSchema),
+        });
+      }
+      if (entry.children?.length) visit(entry.children);
+    }
+  };
+  visit(scope.entries);
+  return out;
+}
+
+function extractEnum(
+  jsonSchema: Record<string, unknown> | undefined,
+): Array<string | number | boolean> | undefined {
+  const candidate = jsonSchema?.enum;
+  if (!Array.isArray(candidate)) return undefined;
+  const usable = candidate.filter(
+    (v): v is string | number | boolean =>
+      typeof v === "string" ||
+      typeof v === "number" ||
+      typeof v === "boolean",
+  );
+  return usable.length > 0 ? usable : undefined;
+}

package/src/editor/trigger-helpers.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "bun:test";
+import type { Trigger } from "@checkstack/automation-common";
+import {
+  assignDefaultTriggerIds,
+  collectTriggerIds,
+  defaultTriggerId,
+} from "./trigger-helpers";
+
+describe("trigger-helpers", () => {
+  it("derives a default id from the event when none is set", () => {
+    expect(defaultTriggerId({ event: "incident.created" }, new Set())).toBe(
+      "incident_created",
+    );
+  });
+
+  it("dedupes against taken ids with numeric suffixes", () => {
+    const trigger: Trigger = { event: "incident.created" };
+    expect(defaultTriggerId(trigger, new Set(["incident_created"]))).toBe(
+      "incident_created_2",
+    );
+    expect(
+      defaultTriggerId(
+        trigger,
+        new Set(["incident_created", "incident_created_2"]),
+      ),
+    ).toBe("incident_created_3");
+  });
+
+  it("collects only non-empty ids", () => {
+    const triggers: Trigger[] = [
+      { event: "a", id: "x" },
+      { event: "b" },
+      { event: "c", id: "" },
+    ];
+    expect([...collectTriggerIds(triggers)]).toEqual(["x"]);
+  });
+
+  it("assigns unique ids to triggers missing them, preserving existing", () => {
+    const out = assignDefaultTriggerIds([
+      { event: "incident.created", id: "primary" },
+      { event: "incident.created" },
+      { event: "maintenance.created" },
+    ]);
+    expect(out[0]!.id).toBe("primary");
+    expect(out[1]!.id).toBe("incident_created");
+    expect(out[2]!.id).toBe("maintenance_created");
+    expect(new Set(out.map((t) => t.id)).size).toBe(3);
+  });
+
+  it("makes two triggers on the same event distinguishable", () => {
+    const out = assignDefaultTriggerIds([
+      { event: "incident.created" },
+      { event: "incident.created" },
+    ]);
+    expect(out[0]!.id).toBe("incident_created");
+    expect(out[1]!.id).toBe("incident_created_2");
+  });
+});

package/src/editor/trigger-helpers.ts

@@ -0,0 +1,67 @@
+import type { Trigger } from "@checkstack/automation-common";
+import { deriveTriggerId } from "@checkstack/automation-common";
+
+/**
+ * Auto-id helpers for triggers, mirroring `action-helpers` for actions.
+ *
+ * A trigger's `id` is what `trigger.id` resolves to at runtime and the
+ * discriminator that distinguishes triggers in templates / scripts - including
+ * two triggers subscribed to the same `event`. The editor assigns a unique,
+ * log-friendly default so the operator never has to, but can rename it.
+ */
+
+/** Base id for a trigger: derived from its event id, falling back to `trigger`. */
+function suggestTriggerIdBase(trigger: Trigger): string {
+  return deriveTriggerId(trigger.event) || "trigger";
+}
+
+/** Collect every assigned (non-empty) trigger id into a set. */
+export function collectTriggerIds(
+  triggers: Trigger[],
+  into: Set<string> = new Set(),
+): Set<string> {
+  for (const trigger of triggers) {
+    if (typeof trigger.id === "string" && trigger.id.length > 0) {
+      into.add(trigger.id);
+    }
+  }
+  return into;
+}
+
+/** Make `base` unique against `taken`, appending `_2`, `_3`, ... as needed. */
+function uniqueTriggerId(base: string, taken: Set<string>): string {
+  if (!taken.has(base)) return base;
+  let n = 2;
+  while (taken.has(`${base}_${n}`)) n += 1;
+  return `${base}_${n}`;
+}
+
+/**
+ * A single identifier-safe, unique default id for `trigger`, deduped against
+ * `taken`. Used to seed a new trigger and to re-fill the Id field when the
+ * operator clears it.
+ */
+export function defaultTriggerId(
+  trigger: Trigger,
+  taken: Set<string>,
+): string {
+  return uniqueTriggerId(suggestTriggerIdBase(trigger), taken);
+}
+
+/**
+ * Return a copy of `triggers` with a stable, unique id assigned to every
+ * trigger that does not already have one. Existing ids are preserved and seed
+ * the uniqueness set. Used when seeding the starter automation so the id is
+ * shown immediately rather than appearing blank.
+ */
+export function assignDefaultTriggerIds(
+  triggers: Trigger[],
+  taken: Set<string> = collectTriggerIds(triggers),
+): Trigger[] {
+  return triggers.map((trigger) => {
+    if (typeof trigger.id === "string" && trigger.id.length > 0) return trigger;
+    const id = uniqueTriggerId(suggestTriggerIdBase(trigger), taken);
+    taken.add(id);
+    return { ...trigger, id };
+  });
+}

package/src/editor/useConnectionOptionResolvers.ts

@@ -0,0 +1,80 @@
+import React from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { IntegrationApi } from "@checkstack/integration-common";
+import type { OptionsResolver } from "@checkstack/ui";
+
+/**
+ * Resolver name for the connection picker itself. Mirrors the
+ * `CONNECTION_OPTIONS` constant every integration provider defines
+ * (`provider.ts` → `*_RESOLVERS.CONNECTION_OPTIONS`). The bridge resolves
+ * this one via `listConnections` (no connection is selected yet) and every
+ * other resolver name via `getConnectionOptions` (cascading dropdowns that
+ * depend on the chosen `connectionId`).
+ */
+const CONNECTION_RESOLVER_NAME = "connectionOptions";
+
+/**
+ * Bridges a connection-backed action's `x-options-resolver` schema fields to
+ * the integration RPC contract so the automation editor's `DynamicForm` can
+ * render a working connection picker plus cascading provider dropdowns.
+ *
+ * Returns a stable, name-agnostic resolver map: the `connectionOptions`
+ * resolver lists the provider's connections, and any other resolver name is
+ * forwarded to `getConnectionOptions` for the currently selected connection,
+ * passing the live form values as `context` for dependent fields.
+ *
+ * When `connectionProviderId` is undefined (a non-connection action such as
+ * Log or Run Script), an empty map is returned so nothing tries to resolve.
+ */
+export function useConnectionOptionResolvers(
+  connectionProviderId?: string,
+): Record<string, OptionsResolver> {
+  const client = usePluginClient(IntegrationApi);
+
+  return React.useMemo(() => {
+    if (!connectionProviderId) return {};
+    const providerId = connectionProviderId;
+
+    // A Proxy lets us serve a resolver for any resolver name a provider's
+    // schema references without enumerating them here; the field component
+    // only ever reads `optionsResolvers[resolverName]`.
+    const handler: ProxyHandler<Record<string, OptionsResolver>> = {
+      get: (_target, prop) => {
+        if (typeof prop !== "string") return;
+        const resolverName = prop;
+
+        const resolver: OptionsResolver = async (formValues) => {
+          if (resolverName === CONNECTION_RESOLVER_NAME) {
+            const connections = await client.listConnections.call({
+              providerId,
+            });
+            return connections.map((connection) => ({
+              value: connection.id,
+              label: connection.name,
+            }));
+          }
+
+          const connectionId = formValues.connectionId;
+          if (typeof connectionId !== "string" || connectionId.length === 0) {
+            return [];
+          }
+
+          const options = await client.getConnectionOptions.call({
+            providerId,
+            connectionId,
+            resolverName,
+            context: formValues,
+          });
+          return options.map((option) => ({
+            value: option.value,
+            label: option.label,
+          }));
+        };
+
+        return resolver;
+      },
+    };
+
+    return new Proxy<Record<string, OptionsResolver>>({}, handler);
+  }, [client, connectionProviderId]);
+}

package/src/editor/yaml-markers.ts

@@ -0,0 +1,116 @@
+import { parseDocument } from "yaml";
+import type { EditorMarker } from "@checkstack/ui";
+
+export interface DefinitionIssue {
+  path: Array<string | number>;
+  message: string;
+}
+
+/**
+ * Map definition validation issues (and YAML syntax errors) onto inline
+ * Monaco markers so the editor squiggles the exact offending node
+ * instead of listing errors in a side panel.
+ *
+ * For each semantic issue we navigate the YAML document to the node at
+ * the issue's `path` and use its source range. When the node doesn't
+ * exist (e.g. a missing required field), we walk up the path to the
+ * nearest existing ancestor and mark that — so the operator is pointed
+ * at the right block even when the key itself is absent.
+ *
+ * Syntax errors come straight from the parser's own `errors` (which
+ * carry source offsets), so malformed YAML is squiggled too.
+ */
+export function computeYamlMarkers(
+  yamlText: string,
+  issues: DefinitionIssue[],
+): EditorMarker[] {
+  const doc = parseDocument(yamlText, { keepSourceTokens: true });
+  const markers: EditorMarker[] = [];
+
+  // 1. Syntax errors from the parser.
+  for (const error of doc.errors) {
+    const [start, end] = error.pos;
+    markers.push(rangeToMarker(yamlText, start, end, error.message));
+  }
+
+  // 2. Semantic issues mapped to their node's range.
+  for (const issue of issues) {
+    const range = resolveRange(doc, issue.path);
+    if (range) {
+      markers.push(
+        rangeToMarker(yamlText, range[0], range[1], issue.message),
+      );
+    } else {
+      // No node anywhere along the path — fall back to the document start.
+      markers.push({
+        startLineNumber: 1,
+        startColumn: 1,
+        endLineNumber: 1,
+        endColumn: 2,
+        message: `${issue.path.join(".") || "(root)"}: ${issue.message}`,
+        severity: "error",
+      });
+    }
+  }
+
+  return markers;
+}
+
+type ParsedDocument = ReturnType<typeof parseDocument>;
+
+/**
+ * Find a source range for `path`, walking up to the nearest existing
+ * ancestor when the exact node is missing.
+ */
+function resolveRange(
+  doc: ParsedDocument,
+  path: Array<string | number>,
+): [number, number] | null {
+  for (let length = path.length; length >= 0; length--) {
+    const node =
+      length === 0
+        ? doc.contents
+        : (doc.getIn(path.slice(0, length), true) as
+            | { range?: [number, number, number] | null }
+            | undefined);
+    const range = node?.range;
+    if (range) return [range[0], range[1]];
+  }
+  return null;
+}
+
+function rangeToMarker(
+  text: string,
+  start: number,
+  end: number,
+  message: string,
+): EditorMarker {
+  const from = offsetToLineCol(text, start);
+  // Guarantee a non-empty highlight even for zero-width ranges.
+  const to = offsetToLineCol(text, Math.max(end, start + 1));
+  return {
+    startLineNumber: from.line,
+    startColumn: from.column,
+    endLineNumber: to.line,
+    endColumn: to.column,
+    message,
+    severity: "error",
+  };
+}
+
+/** Convert a 0-based character offset to a 1-based Monaco line/column. */
+function offsetToLineCol(
+  text: string,
+  offset: number,
+): { line: number; column: number } {
+  const clamped = Math.max(0, Math.min(offset, text.length));
+  let line = 1;
+  let lastLineStart = 0;
+  for (let i = 0; i < clamped; i++) {
+    if (text[i] === "\n") {
+      line += 1;
+      lastLineStart = i + 1;
+    }
+  }
+  return { line, column: clamped - lastLineStart + 1 };
+}

package/src/index.tsx

@@ -0,0 +1,95 @@
+import {
+  createFrontendPlugin,
+  createSlotExtension,
+  UserMenuItemsSlot,
+} from "@checkstack/frontend-api";
+import {
+  automationRoutes,
+  pluginMetadata,
+  automationAccess,
+} from "@checkstack/automation-common";
+import { AutomationListPage } from "./pages/AutomationListPage";
+import { AutomationEditPage } from "./pages/AutomationEditPage";
+import { RunsPage } from "./pages/RunsPage";
+import { RunDetailPage } from "./pages/RunDetailPage";
+import { TemplatePlaygroundPage } from "./pages/TemplatePlaygroundPage";
+import { AutomationMenuItems } from "./components/AutomationMenuItems";
+
+export {
+  generateAutomationContextTypes,
+  type GenerateAutomationContextTypesInput,
+  type GenerateAutomationContextTypesResult,
+} from "./script-context";
+
+/**
+ * Frontend plugin for the automation platform.
+ *
+ * Routes:
+ *
+ *   - `/automation/`                          → list view
+ *   - `/automation/new`                       → blank edit page (create)
+ *   - `/automation/:automationId`             → edit page
+ *   - `/automation/:automationId/runs`        → run history
+ *   - `/automation/:automationId/runs/:runId` → single run drill-down
+ *   - `/automation/playground`                → template playground
+ *
+ * Run history pages and the playground are gated on `automation.read`;
+ * everything that mutates state (create/edit/delete/toggle, manual run,
+ * cancel run) further requires `automation.manage`. The edit page
+ * downgrades gracefully — viewers can read the YAML but the Save / Run
+ * Now / Delete controls disappear.
+ *
+ * No `foreignSignals` declared: every signal the automation domain
+ * emits (`AUTOMATION_DEFINITION_CHANGED`, `AUTOMATION_RUN_*`) is owned
+ * by this plugin, so the auto-invalidator wires it up for free. If
+ * cross-domain signals matter later (e.g. invalidating the run list
+ * when a remote incident closes), declare them here.
+ */
+export default createFrontendPlugin({
+  metadata: pluginMetadata,
+  routes: [
+    {
+      route: automationRoutes.routes.list,
+      element: <AutomationListPage />,
+      title: "Automations",
+      accessRule: automationAccess.read,
+    },
+    {
+      route: automationRoutes.routes.create,
+      element: <AutomationEditPage />,
+      title: "New automation",
+      accessRule: automationAccess.manage,
+    },
+    {
+      route: automationRoutes.routes.edit,
+      element: <AutomationEditPage />,
+      title: "Edit automation",
+      accessRule: automationAccess.read,
+    },
+    {
+      route: automationRoutes.routes.runs,
+      element: <RunsPage />,
+      title: "Run history",
+      accessRule: automationAccess.read,
+    },
+    {
+      route: automationRoutes.routes.runDetail,
+      element: <RunDetailPage />,
+      title: "Run details",
+      accessRule: automationAccess.read,
+    },
+    {
+      route: automationRoutes.routes.playground,
+      element: <TemplatePlaygroundPage />,
+      title: "Template playground",
+      accessRule: automationAccess.read,
+    },
+  ],
+  extensions: [
+    createSlotExtension(UserMenuItemsSlot, {
+      id: "automation.user-menu.items",
+      component: AutomationMenuItems,
+      metadata: { group: "Automation" },
+    }),
+  ],
+});