@fieldwork-ai/cli 0.17.1 → 0.19.0

package/README.md

@@ -43,6 +43,8 @@ Mutations prompt for confirmation on a TTY; pass `--yes` to skip (required in no
 
 The connector development loop end to end: `connectors pull acme_erp` → edit the adapter → `connectors publish acme_erp --message "…" --base-revision N` (a new key creates the definition from the tree's `connector.json`) → `connectors connect acme_erp --spec spec.json` → `connectors secrets set <id>` → `automations run-now <sync> --follow` to watch the logs.
 
+Publishing initializes a new connector from `connector.json`, but subsequent action revisions leave `connector_definitions` metadata unchanged. To edit its display name, description, branding, or REST secret-name hints, use `fieldwork connectors metadata <definition-id>`, then `fieldwork connectors update-metadata <definition-id> --changes changes.json --expected-updated-at '<exact updated_at from the read>'`. The update requires connector edit access and rejects stale reads; credential values are managed separately through `secrets`.
+
 ## Auth and configuration
 
 Credential resolution order: the injected container file (`~/.fieldwork/credentials`) → `FIELDWORK_TOKEN` / `FIELDWORK_API_URL` environment variables → the `fieldwork login` config (`~/.config/fieldwork/config.json`). One token binds one organization; `fieldwork orgs use` re-runs the browser flow to switch. Revoke a login anytime in Fieldwork under Settings → Connected apps.
@@ -62,3 +64,7 @@ claude mcp add --transport http fieldwork https://app.getfieldwork.ai/mcp
 Source stays in the private app repository under `cli/`. Run `pnpm install --frozen-lockfile`, `pnpm build`, and `pnpm test` here. Publish the compiled package with `npm publish --access public`; the package includes `dist/` and npm metadata, without TypeScript source or source maps. `scripts/pack-cli.sh` builds and packs this same package into the compute image without depending on an npm release.
 
 The terminal chat client is the separate public `@fieldwork-ai/fieldwork-code` package (`fwcode`).
+
+## Graph authoring diagnostics
+
+Use `fieldwork tool run automations_graph_examples --json` for executable examples and the coordinated code/graph publication format. `automations_graph_validate` takes the publication input without committing it. `automations_graph_test` uses isolated editable-table fixtures and captured notifications; it does not execute authored code or send email. `automations_graph_wait` returns bounded, compact progress, and `automations_graph_trace` accepts `detail: "full"` when saved payloads are needed. Contract failures include source/destination paths, required coordinated changes and retryability on stderr with a nonzero exit code.

package/dist/commands/automations.js

@@ -71,7 +71,9 @@ async function followRun(automationId, runId, intervalSeconds, json) {
     }
 }
 export function registerAutomationCommands(program) {
-    const graph = program.command("automation-graph").description("Publish and inspect automation graphs");
+    const graph = program
+        .command("automation-graph", { hidden: true })
+        .description("Publish and inspect automation graphs");
     graph.command("get <automation-id>").action(async (id) => printData(await apiJson(`/api/organizations/${requireOrgId()}/automations/${encodeURIComponent(id)}/graph`), true));
     graph.command("trace <automation-id> <run-id>").action(async (id, runId) => printData(await apiJson(`/api/organizations/${requireOrgId()}/automations/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/steps`), true));
     graph.command("configure <automation-id>").requiredOption("--file <path>").action(async (id, options) => {
@@ -91,7 +93,61 @@ export function registerAutomationCommands(program) {
     });
     const automations = program
         .command("automations")
-        .description("Standing instructions that run unattended (schedules, webhooks)");
+        .description("Create, manage and inspect automations");
+    const callTool = async (name, args) => {
+        const response = await apiJson("/api/tools/run", {
+            method: "POST",
+            body: JSON.stringify({ name, args }),
+        });
+        printData(response.result, true);
+    };
+    for (const operation of ["publish", "validate", "test", "update"]) {
+        automations
+            .command(operation)
+            .description(`${operation} an automation`)
+            .requiredOption("--file <path>")
+            .action(async (options) => {
+            const input = JSON.parse(await readFile(options.file, "utf8"));
+            if (operation === "publish" || operation === "update")
+                await confirm(`Apply this automation ${operation}?`, getContext().yes);
+            await callTool(`automations_${operation}`, input);
+        });
+    }
+    automations
+        .command("run <name>")
+        .description("Start a real automation run")
+        .option("--input <path>", "File containing the run input")
+        .action(async (name, options) => {
+        const input = options.input
+            ? JSON.parse(await readFile(options.input, "utf8"))
+            : undefined;
+        await confirm(`Run "${name}" now?`, getContext().yes);
+        await callTool("automations_run", { name, input });
+    });
+    automations
+        .command("examples")
+        .description("Working automation definitions and tests")
+        .action(() => callTool("automations_examples", {}));
+    for (const operation of ["get-run", "wait"]) {
+        automations
+            .command(`${operation} <name> <run-id>`)
+            .description(operation === "wait" ? "Wait briefly for a run" : "Inspect one run")
+            .action((name, runId) => callTool(`automations_${operation.replaceAll("-", "_")}`, {
+            name,
+            automation_run_id: runId,
+            ...(operation === "get-run" ? { detail: "full" } : {}),
+        }));
+    }
+    automations
+        .command("control <name> <run-id>")
+        .description("Cancel, retry, or reconcile a run")
+        .requiredOption("--file <path>")
+        .action(async (name, runId, options) => {
+        const found = await resolveAutomation(name);
+        const body = await readFile(options.file, "utf8");
+        await confirm("Apply this run control? Verify external results before reconciliation.", getContext().yes);
+        printData(await apiJson(`/api/organizations/${requireOrgId()}/automations/${found.automation_id}/runs/${encodeURIComponent(runId)}/steps`, { method: "POST", body }), true);
+    });
     automations
         .command("list")
         .description("List the automations you can see")
@@ -112,12 +168,8 @@ export function registerAutomationCommands(program) {
     });
     automations
         .command("get <name>")
-        .description("One automation in full (includes the webhook URL — treat as a credential)")
-        .action(async (name) => {
-        const found = await resolveAutomation(name);
-        const body = await apiJson(`/api/organizations/${requireOrgId()}/automations/${found.automation_id}`);
-        printData(body, getContext().json);
-    });
+        .description("Read an automation definition, settings and recent runs")
+        .action((name) => callTool("automations_get", { name }));
     const setEnabled = (enabled) => async (name) => {
         const { json, yes } = getContext();
         const found = await resolveAutomation(name);
@@ -171,10 +223,14 @@ export function registerAutomationCommands(program) {
         .action(async (name, opts) => {
         const { json } = getContext();
         const found = await resolveAutomation(name);
-        const query = opts.run ? `?run=${encodeURIComponent(opts.run)}` : "?limit=1";
+        const query = opts.run
+            ? `?run=${encodeURIComponent(opts.run)}`
+            : "?limit=1";
         const run = (await fetchRuns(found.automation_id, query))[0];
         if (!run) {
-            fail(opts.run ? `no run ${opts.run} for "${name}"` : `"${name}" has no runs yet`, EXIT.notFound);
+            fail(opts.run
+                ? `no run ${opts.run} for "${name}"`
+                : `"${name}" has no runs yet`, EXIT.notFound);
         }
         printRun(run, json);
     });

package/dist/commands/connectors.js

@@ -223,6 +223,26 @@ export function registerConnectorCommands(program) {
         });
         printData(body, json);
     });
+    connectors.command("metadata <definition-id>")
+        .description("Read an org-private connector definition's editable metadata")
+        .action(async (id) => {
+        printData(await apiJson(`/api/organizations/${requireOrgId()}/connector-definitions/${id}`), getContext().json);
+    });
+    connectors.command("update-metadata <definition-id>")
+        .description("Edit connector metadata separately from action code")
+        .requiredOption("--changes <json-file>", "metadata fields to change")
+        .requiredOption("--expected-updated-at <timestamp>", "exact updated_at from metadata read")
+        .action(async (id, opts) => {
+        const url = `/api/organizations/${requireOrgId()}/connector-definitions/${id}`;
+        const before = await apiJson(url);
+        if (before.updated_at !== opts.expectedUpdatedAt)
+            fail("Connector metadata changed; read it again before updating", EXIT.conflict);
+        const changes = JSON.parse(readFileSync(opts.changes, "utf8"));
+        await confirm(`Update connector metadata? Before: ${JSON.stringify(before.metadata)} Changes: ${JSON.stringify(changes)}`, getContext().yes);
+        printData(await apiJson(url, {
+            method: "PATCH", body: JSON.stringify({ expected_updated_at: opts.expectedUpdatedAt, changes }),
+        }), getContext().json);
+    });
     const secrets = connectors
         .command("secrets")
         .description("Connector credentials (values never transit argv or stdout)");

package/dist/http.js

@@ -121,6 +121,16 @@ export async function apiJson(pathname, init = {}) {
             const { path, message } = issue;
             return typeof message === "string" ? [`${Array.isArray(path) ? path.join(".") + ": " : ""}${message}`] : [];
         }) : [];
+        if (body?.code === "invalid_graph" && body.details && typeof body.details === "object" && !Array.isArray(body.details)) {
+            const diagnostic = body.details;
+            for (const key of ["action_definition_id", "automation_id", "automation_revision_id", "node_id", "source", "destination", "input", "output", "source_schema", "target_schema", "effect_changed", "credential_changed", "required_action"]) {
+                const value = diagnostic[key];
+                if (value !== undefined && value !== null)
+                    details.push(`${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+            }
+            if (typeof body.retryable === "boolean")
+                details.push(`retryable: ${body.retryable}`);
+        }
         const prefix = typeof body?.tool === "string" ? `${body.tool}: ` : "";
         fail([prefix + message, ...details].join("\n"), exitCodeFor(res.status));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fieldwork-ai/cli",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "Fieldwork asset-management CLI",
   "license": "UNLICENSED",
   "type": "module",