@agentled/cli 0.7.1 → 0.7.4

package/dist/commands/workflows.js

@@ -37,7 +37,26 @@ function formatIssueLine(issue) {
 async function runAutoValidate(client, workflowId, opts) {
     let result;
     try {
-        result = await client.validateWorkflow(workflowId);
+        let pipeline;
+        let validationSource = 'live';
+        if (opts.source === 'draft' || opts.source === 'auto') {
+            try {
+                const draft = await client.getDraft(workflowId);
+                if (draft?.draft?.config) {
+                    pipeline = draft.draft.config;
+                    validationSource = 'draft';
+                }
+                else if (opts.source === 'draft') {
+                    throw new Error(`No draft exists for workflow ${workflowId}`);
+                }
+            }
+            catch (e) {
+                if (opts.source === 'draft')
+                    throw e;
+            }
+        }
+        result = await client.validateWorkflow(workflowId, pipeline);
+        result = { ...result, source: validationSource };
     }
     catch (e) {
         // The workflow was saved; only the post-hoc validate call failed.
@@ -51,6 +70,9 @@ async function runAutoValidate(client, workflowId, opts) {
     if (opts.format !== 'json') {
         const errorCount = result.errors?.length ?? 0;
         const warnCount = result.warnings?.length ?? 0;
+        if (result.source && result.source !== 'live') {
+            console.log(`  Source: ${result.source}`);
+        }
         if (errorCount === 0 && warnCount === 0) {
             console.log(`  ✓ Validated (0 errors, 0 warnings) — ${workflowId}`);
         }
@@ -90,6 +112,145 @@ function exitCodeForOutcome(outcome) {
         return VALIDATION_EXIT_CODE;
     return 1;
 }
+const CONFIG_UPDATE_FIELDS = ['name', 'goal', 'description', 'steps', 'context', 'style', 'analyticsConfig'];
+const READ_ONLY_WORKFLOW_FIELDS = new Set([
+    '_agentled',
+    'id',
+    'workspaceId',
+    'workspace',
+    'createdAt',
+    'updatedAt',
+    'owner',
+    'executions',
+    'executionInputs',
+    'computedMetrics',
+    'notificationBadge',
+    'agents',
+    'team',
+    'hasDraftSnapshot',
+    'draftSnapshot',
+    'urls',
+]);
+function normalizeRevision(value) {
+    const revision = typeof value === 'number'
+        ? value
+        : typeof value === 'string'
+            ? Number.parseInt(value, 10)
+            : Number.NaN;
+    return Number.isFinite(revision) && revision >= 0 ? revision : undefined;
+}
+function pickWorkflowConfig(workflow) {
+    const config = {};
+    for (const key of CONFIG_UPDATE_FIELDS) {
+        if (workflow[key] !== undefined)
+            config[key] = workflow[key];
+    }
+    return config;
+}
+function getWorkflowFromResponse(result) {
+    return (result?.workflow && typeof result.workflow === 'object') ? result.workflow : result;
+}
+function normalizeWorkflowUpdateFile(parsed) {
+    let source;
+    let updates = parsed;
+    if (parsed?.export?.pipeline) {
+        updates = parsed.export.pipeline;
+        source = parsed.export.sourceWorkflow;
+    }
+    else if (parsed?.exportVersion && parsed?.pipeline) {
+        updates = parsed.pipeline;
+        source = parsed.sourceWorkflow;
+    }
+    else if (parsed?.workflow) {
+        updates = parsed.workflow;
+        source = {
+            workflowId: parsed.workflow.id,
+            updatedAt: parsed.workflow.updatedAt,
+            revision: normalizeRevision(parsed.workflow.metadata?.revision),
+            status: parsed.workflow.status,
+        };
+    }
+    else if (parsed?._agentled) {
+        source = {
+            workflowId: parsed._agentled.workflowId,
+            updatedAt: parsed._agentled.updatedAt,
+            revision: normalizeRevision(parsed._agentled.revision),
+            status: parsed._agentled.status,
+        };
+    }
+    const cleaned = {};
+    for (const [key, value] of Object.entries(updates || {})) {
+        if (!READ_ONLY_WORKFLOW_FIELDS.has(key))
+            cleaned[key] = value;
+    }
+    return { updates: cleaned, source };
+}
+function hasConfigUpdate(updates) {
+    return CONFIG_UPDATE_FIELDS.some((field) => Object.prototype.hasOwnProperty.call(updates, field));
+}
+function buildPulledWorkflowFile(workflow) {
+    return {
+        _agentled: {
+            kind: 'workflow-update-file',
+            workflowId: workflow.id,
+            updatedAt: workflow.updatedAt,
+            revision: normalizeRevision(workflow.metadata?.revision),
+            status: workflow.status,
+            pulledAt: new Date().toISOString(),
+        },
+        ...pickWorkflowConfig(workflow),
+    };
+}
+function diffWorkflowConfig(remote, updates) {
+    const changedFields = CONFIG_UPDATE_FIELDS.filter((field) => Object.prototype.hasOwnProperty.call(updates, field)
+        && JSON.stringify(remote[field] ?? null) !== JSON.stringify(updates[field] ?? null));
+    const remoteSteps = Array.isArray(remote.steps) ? remote.steps : [];
+    const nextSteps = Array.isArray(updates.steps) ? updates.steps : remoteSteps;
+    const remoteIds = new Set(remoteSteps.map((step) => step?.id).filter(Boolean));
+    const nextIds = new Set(nextSteps.map((step) => step?.id).filter(Boolean));
+    const addedSteps = Array.from(nextIds).filter((id) => !remoteIds.has(id));
+    const removedSteps = Array.from(remoteIds).filter((id) => !nextIds.has(id));
+    const changedSteps = nextSteps
+        .filter((step) => step?.id && remoteIds.has(step.id))
+        .filter((step) => {
+        const previous = remoteSteps.find((candidate) => candidate?.id === step.id);
+        return JSON.stringify(previous ?? null) !== JSON.stringify(step ?? null);
+    })
+        .map((step) => step.id);
+    return { changedFields, addedSteps, removedSteps, changedSteps };
+}
+async function verifySafeFileUpdate(client, workflowId, filePath, updates, source, opts) {
+    if (!hasConfigUpdate(updates) || opts.force)
+        return true;
+    const remote = getWorkflowFromResponse(await client.getWorkflow(workflowId));
+    const expectedUpdatedAt = opts.expectedUpdatedAt || source?.updatedAt;
+    const expectedRevision = normalizeRevision(source?.revision);
+    const remoteRevision = normalizeRevision(remote.metadata?.revision);
+    if (source?.workflowId && source.workflowId !== workflowId) {
+        printError(`File was pulled from workflow ${source.workflowId}, not ${workflowId}. Pull the target workflow first or use --force.`);
+        return false;
+    }
+    if (expectedRevision !== undefined && remoteRevision !== undefined) {
+        if (expectedRevision !== remoteRevision) {
+            printError(`Refusing stale update. File is based on revision ${expectedRevision}, but remote is revision ${remoteRevision}. ` +
+                `Run: agentled workflows pull ${workflowId} --output ${filePath} --force, compare/re-apply your edits, then update or replace again.`);
+            return false;
+        }
+        return true;
+    }
+    if (!expectedUpdatedAt) {
+        printError('Refusing config update from a file without a remote revision or updatedAt token. ' +
+            `Run: agentled workflows pull ${workflowId} --output ${filePath} --force, re-apply your edits, then run workflows diff/replace. ` +
+            'Use --force only when you intentionally want to overwrite remote config.');
+        return false;
+    }
+    if (expectedUpdatedAt !== remote.updatedAt) {
+        printError(`Refusing stale update. File is based on ${expectedUpdatedAt}, but remote is ${remote.updatedAt}. ` +
+            `Run: agentled workflows pull ${workflowId} --output ${filePath} --force, compare/re-apply your edits, then update or replace again.`);
+        return false;
+    }
+    return true;
+}
 export function registerWorkflowCommands(program) {
     const workflows = program
         .command('workflows')
@@ -131,25 +292,39 @@ export function registerWorkflowCommands(program) {
     });
     workflows
         .command('pull <id>')
-        .description('Pull a live workflow into examples/live/<name>-<id>.json and generate a test skeleton at tests/<id>.test.json. Use after `agentled init` to start iterating locally.')
+        .description('Pull a workflow into an update-safe local file with a remote updatedAt token. Use this before workflows update --file.')
+        .option('--output <path>', 'Write workflow config to a specific path')
         .option('--force', 'Overwrite existing files', false)
         .option('--format <fmt>', 'Output format', 'json')
         .action(async (id, opts) => {
         try {
             const client = new AgentledClient();
-            const workflow = await client.getWorkflow(id);
-            const pipeline = (workflow.pipeline ?? workflow);
+            const result = await client.getWorkflow(id);
+            const pipeline = getWorkflowFromResponse(result);
+            const updateFile = buildPulledWorkflowFile(pipeline);
             const wsDir = findWorkspaceDir();
             const name = String(pipeline.name ?? id).toLowerCase().replace(/[^a-z0-9]+/g, '-');
             const filename = `${name}-${id}.json`;
             let savedPath;
             let testPath = null;
             let testSkippedReason = null;
-            if (wsDir) {
+            if (opts.output) {
+                savedPath = resolve(opts.output);
+                if (fs.existsSync(savedPath) && !opts.force) {
+                    printError(`Refusing to overwrite ${savedPath}. Use --force to overwrite.`);
+                    return;
+                }
+                fs.writeFileSync(savedPath, JSON.stringify(updateFile, null, 2) + '\n');
+            }
+            else if (wsDir) {
                 const liveDir = join(wsDir, 'examples', 'live');
                 fs.mkdirSync(liveDir, { recursive: true });
                 savedPath = join(liveDir, filename);
-                fs.writeFileSync(savedPath, JSON.stringify(pipeline, null, 2) + '\n');
+                if (fs.existsSync(savedPath) && !opts.force) {
+                    printError(`Refusing to overwrite ${savedPath}. Use --force to overwrite.`);
+                    return;
+                }
+                fs.writeFileSync(savedPath, JSON.stringify(updateFile, null, 2) + '\n');
                 const testsDir = join(wsDir, 'tests');
                 fs.mkdirSync(testsDir, { recursive: true });
                 testPath = join(testsDir, `${id}.test.json`);
@@ -163,7 +338,11 @@ export function registerWorkflowCommands(program) {
             }
             else {
                 savedPath = resolve(filename);
-                fs.writeFileSync(savedPath, JSON.stringify(pipeline, null, 2) + '\n');
+                if (fs.existsSync(savedPath) && !opts.force) {
+                    printError(`Refusing to overwrite ${savedPath}. Use --force to overwrite.`);
+                    return;
+                }
+                fs.writeFileSync(savedPath, JSON.stringify(updateFile, null, 2) + '\n');
             }
             const allSteps = (Array.isArray(pipeline.steps) ? pipeline.steps : []);
             const testableCount = allSteps.filter((s) => ['aiAction', 'aiActionWithTools', 'appAction', 'code'].includes(String(s.type ?? ''))).length;
@@ -177,6 +356,9 @@ export function registerWorkflowCommands(program) {
                 stepCount: allSteps.length,
                 testableSteps: testableCount,
                 nextSteps: [
+                    `edit ${savedPath}`,
+                    `agentled workflows diff ${id} --file ${savedPath}`,
+                    `agentled workflows replace ${id} --file ${savedPath}`,
                     `agentled workflows start ${id}     # run once to capture fixtures`,
                     `agentled fixture capture <execId> --wf ${id}`,
                     `agentled test ${id}                # run assertions against fixtures`,
@@ -187,6 +369,52 @@ export function registerWorkflowCommands(program) {
             printError(e instanceof Error ? e.message : String(e));
         }
     });
+    workflows
+        .command('diff <id>')
+        .description('Compare a local workflow update file with the current remote workflow before updating.')
+        .requiredOption('--file <path>', 'Path to workflow update JSON file')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (id, opts) => {
+        try {
+            const raw = fs.readFileSync(opts.file, 'utf-8');
+            const { updates, source } = normalizeWorkflowUpdateFile(JSON.parse(raw));
+            const client = new AgentledClient();
+            const remote = getWorkflowFromResponse(await client.getWorkflow(id));
+            const diff = diffWorkflowConfig(remote, updates);
+            const remoteRevision = normalizeRevision(remote.metadata?.revision);
+            const sourceRevision = normalizeRevision(source?.revision);
+            const sourceMatchesRemote = sourceRevision !== undefined && remoteRevision !== undefined
+                ? sourceRevision === remoteRevision
+                : source?.updatedAt
+                    ? source.updatedAt === remote.updatedAt
+                    : undefined;
+            printOutput({
+                workflowId: id,
+                file: resolve(opts.file),
+                remoteRevision,
+                fileSourceRevision: sourceRevision,
+                remoteUpdatedAt: remote.updatedAt,
+                fileSourceUpdatedAt: source?.updatedAt,
+                sourceMatchesRemote,
+                stale: sourceMatchesRemote === false,
+                ...diff,
+                summary: {
+                    changedFields: diff.changedFields.length,
+                    addedSteps: diff.addedSteps.length,
+                    removedSteps: diff.removedSteps.length,
+                    changedSteps: diff.changedSteps.length,
+                },
+                nextStep: sourceMatchesRemote === false
+                    ? `Remote changed since this file was pulled. Run: agentled workflows pull ${id} --output ${opts.file} --force, then re-apply your edits.`
+                    : `If this diff is intended, run: agentled workflows replace ${id} --file ${opts.file}`,
+            }, (opts.format ?? 'json'));
+            if (sourceMatchesRemote === false)
+                process.exitCode = 1;
+        }
+        catch (e) {
+            printError(e instanceof Error ? e.message : String(e));
+        }
+    });
     workflows
         .command('lint <file>')
         .description('Static gotcha checks for a pipeline JSON file (no API). Catches 11 documented failure modes (criteria/conditions, Gmail label_id, missing tools, email shape, etc.). For platform validators (graph wiring, variable resolution), run `agentled workflows validate <id>` after creating the workflow.')
@@ -296,15 +524,20 @@ export function registerWorkflowCommands(program) {
         .description('Update an existing workflow (auto-validates unless --skip-validate)')
         .option('--file <path>', 'Path to updates JSON file')
         .option('--updates <json>', 'Inline updates JSON')
+        .option('--expected-updated-at <timestamp>', 'Require the remote workflow updatedAt to match before applying --file')
+        .option('--force', 'Bypass the --file stale-update guard (advanced)')
         .option('--locale <locale>', 'Locale')
         .option('--format <fmt>', 'Output format', 'json')
         .option('--skip-validate', 'Skip the post-update validate call (advanced)')
         .action(async (id, opts) => {
         try {
             let updates;
+            let source;
             if (opts.file) {
                 const raw = fs.readFileSync(opts.file, 'utf-8');
-                updates = JSON.parse(raw);
+                const normalized = normalizeWorkflowUpdateFile(JSON.parse(raw));
+                updates = normalized.updates;
+                source = normalized.source;
             }
             else if (opts.updates) {
                 updates = JSON.parse(opts.updates);
@@ -315,6 +548,14 @@ export function registerWorkflowCommands(program) {
             }
             const client = new AgentledClient();
             const format = (opts.format ?? 'json');
+            if (opts.file) {
+                const safe = await verifySafeFileUpdate(client, id, opts.file, updates, source, {
+                    force: opts.force,
+                    expectedUpdatedAt: opts.expectedUpdatedAt,
+                });
+                if (!safe)
+                    return;
+            }
             const result = await client.updateWorkflow(id, updates, opts.locale);
             if (opts.skipValidate) {
                 printOutput(result, format);
@@ -324,7 +565,10 @@ export function registerWorkflowCommands(program) {
                 // Preserve the update mutation response fields in the JSON
                 // envelope — `result` may contain the refreshed workflow
                 // record, which script consumers parse.
-                const outcome = await runAutoValidate(client, id, { format });
+                const outcome = await runAutoValidate(client, id, {
+                    format,
+                    source: result?.editingDraft ? 'draft' : 'live',
+                });
                 const validation = outcome.status === 'request-failed'
                     ? { requestFailed: true }
                     : outcome.result;
@@ -338,7 +582,64 @@ export function registerWorkflowCommands(program) {
                 return;
             }
             printOutput(result, format);
-            const outcome = await runAutoValidate(client, id, { format });
+            const outcome = await runAutoValidate(client, id, {
+                format,
+                source: result?.editingDraft ? 'draft' : 'live',
+            });
+            const code = exitCodeForOutcome(outcome);
+            if (code !== 0)
+                process.exit(code);
+        }
+        catch (e) {
+            printError(e.message);
+        }
+    });
+    workflows
+        .command('replace <id>')
+        .description('Replace workflow config fields from a pulled file. Uses true replace semantics for context and validates draft when editing live workflows.')
+        .requiredOption('--file <path>', 'Path to workflow JSON from workflows pull/export')
+        .option('--expected-updated-at <timestamp>', 'Require the remote workflow updatedAt to match before replacing')
+        .option('--force', 'Bypass the stale-file guard (advanced)')
+        .option('--locale <locale>', 'Locale')
+        .option('--format <fmt>', 'Output format', 'json')
+        .option('--skip-validate', 'Skip the post-replace validate call (advanced)')
+        .action(async (id, opts) => {
+        try {
+            const raw = fs.readFileSync(opts.file, 'utf-8');
+            const { updates, source } = normalizeWorkflowUpdateFile(JSON.parse(raw));
+            const client = new AgentledClient();
+            const format = (opts.format ?? 'json');
+            const safe = await verifySafeFileUpdate(client, id, opts.file, updates, source, {
+                force: opts.force,
+                expectedUpdatedAt: opts.expectedUpdatedAt,
+            });
+            if (!safe)
+                return;
+            const result = await client.replaceWorkflow(id, updates, opts.locale);
+            if (opts.skipValidate) {
+                printOutput(result, format);
+                return;
+            }
+            const validateOpts = {
+                format,
+                source: result?.editingDraft ? 'draft' : 'live',
+            };
+            if (format === 'json') {
+                const outcome = await runAutoValidate(client, id, validateOpts);
+                const validation = outcome.status === 'request-failed'
+                    ? { requestFailed: true }
+                    : outcome.result;
+                const envelope = result && typeof result === 'object'
+                    ? { ...result, validation }
+                    : { workflowId: id, validation };
+                printOutput(envelope, 'json');
+                const code = exitCodeForOutcome(outcome);
+                if (code !== 0)
+                    process.exit(code);
+                return;
+            }
+            printOutput(result, format);
+            const outcome = await runAutoValidate(client, id, validateOpts);
             const code = exitCodeForOutcome(outcome);
             if (code !== 0)
                 process.exit(code);
@@ -366,6 +667,9 @@ export function registerWorkflowCommands(program) {
         .description('Validate a workflow. With <id>: server-side validation. With --file/--pipeline and no id: fast client-side preflight (no API call).')
         .option('--file <path>', 'Path to pipeline JSON file (client-side preflight if no <id> is given)')
         .option('--pipeline <json>', 'Inline pipeline JSON (overrides the saved pipeline when <id> is given; otherwise runs preflight)')
+        .option('--source <src>', 'Validation source when <id> is provided: auto (default) | live | draft', 'auto')
+        .option('--draft', 'Validate the current draft config for this workflow')
+        .option('--live', 'Validate the live stored workflow config')
         .option('--format <fmt>', 'Output format', 'json')
         .action(async (id, opts) => {
         try {
@@ -411,14 +715,51 @@ export function registerWorkflowCommands(program) {
                 return;
             }
             const client = new AgentledClient();
+            if (opts.draft && opts.live) {
+                printError('Use either --draft or --live, not both.');
+                return;
+            }
+            const source = opts.draft ? 'draft' : opts.live ? 'live' : String(opts.source ?? 'auto');
+            if (!['auto', 'live', 'draft'].includes(source)) {
+                printError(`Invalid --source "${source}". Must be one of: auto, live, draft.`);
+                return;
+            }
+            // When source is specified, resolve which stored config to validate:
+            // - draft: validates the current draft pipeline and errors if none exists
+            // - auto: validates draft if present, otherwise live
+            // - live: validates the live stored workflow
+            let resolvedSource = 'live';
+            if (!pipeline && source !== 'live') {
+                try {
+                    const draft = await client.getDraft(id);
+                    if (draft?.draft?.config) {
+                        pipeline = draft.draft.config;
+                        resolvedSource = 'draft';
+                    }
+                    else if (source === 'draft') {
+                        printError(`No draft exists for workflow ${id}.`);
+                        return;
+                    }
+                }
+                catch {
+                    if (source === 'draft') {
+                        printError(`No draft exists for workflow ${id}.`);
+                        return;
+                    }
+                }
+            }
             const result = await client.validateWorkflow(id, pipeline);
             const format = opts.format;
+            const validationSource = opts.pipeline || opts.file
+                ? 'inline'
+                : (pipeline ? resolvedSource : 'live');
             if (format === 'json') {
-                printOutput(result, 'json');
+                printOutput({ ...result, source: validationSource }, 'json');
             }
             else {
                 const errorCount = result.errors?.length ?? 0;
                 const warnCount = result.warnings?.length ?? 0;
+                console.log(`  Source: ${validationSource}`);
                 if (errorCount === 0 && warnCount === 0) {
                     console.log(`  ✓ Validated (0 errors, 0 warnings) — ${id}`);
                 }
@@ -773,13 +1114,30 @@ export function registerWorkflowCommands(program) {
         }
     });
     workflows
-        .command('move-step <workflowId> <stepId> <insertAfter>')
-        .description('Move a step to a new location in a workflow')
+        .command('move-step <workflowId> <stepId> [insertAfter]')
+        .description('Move a step to a new location in a workflow. Use legacy positional <insertAfter>, --after <stepId>, or --position first|last.')
+        .option('--after <stepId>', 'Insert after this step ID')
+        .option('--position <pos>', 'Move to first or last position')
         .option('--format <fmt>', 'Output format', 'json')
         .action(async (workflowId, stepId, insertAfter, opts) => {
         try {
+            const after = opts.after || insertAfter;
+            const position = opts.position;
+            if (!after && !position) {
+                printError('Provide <insertAfter>, --after <stepId>, or --position first|last');
+                return;
+            }
+            if (after && position) {
+                printError('Provide either an insert-after target or --position, not both');
+                return;
+            }
+            if (position && position !== 'first' && position !== 'last') {
+                printError('--position must be "first" or "last"');
+                return;
+            }
             const client = new AgentledClient();
-            const result = await client.moveStep(workflowId, stepId, insertAfter);
+            const target = position ? { position: position } : after;
+            const result = await client.moveStep(workflowId, stepId, target);
             printOutput(result, opts.format);
         }
         catch (e) {