@testchimp/cli 0.1.19 → 0.1.20

package/dist/cli/program.js

@@ -897,6 +897,85 @@ export function buildCliProgram() {
         const out = await runTool("report-requirement-quality-findings", merged, { postMcp });
         console.log(out);
     });
+    // Workflow policy + traceability tools (US-181). Prefer --json-input for nested TestLocator.
+    program
+        .command("report-agent-action")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "report-agent-action").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--workflow-id <id>", "Catalog workflow id")
+        .requiredOption("--workflow-execution-id <ulid>", "Stable ULID for the whole run")
+        .requiredOption("--action-type <type>", "CREATED|UPDATED|DELETED|ANALYZED|ACTION_COMPLETED|ACTION_FAILED")
+        .option("--policy-file <name>", "Policy filename")
+        .option("--policy-version <semver>", "Policy version from frontmatter")
+        .option("--git-sha <sha>", "Current HEAD sha")
+        .option("--actor-type <type>", "LOCAL_AGENT|CLOUD_AGENT (or local-agent|cloud-agent)")
+        .option("--user-id <id>", "Optional user id for traceability")
+        .option("--branch-name <name>", "Git branch")
+        .option("--entity-type <type>", "test|story|scenario|issue|workflow|…")
+        .option("--entity-identity <ordinal>", "Project-scoped ordinal id (mutually exclusive with --test-json)")
+        .option("--test-json <json>", "TestLocator JSON (folderPath/fileName/testSuite/testName)")
+        .option("--detail-json <json>", "Optional detail payload")
+        .action(async (opts) => {
+        const body = {
+            workflowId: String(opts.workflowId),
+            workflowExecutionId: String(opts.workflowExecutionId),
+            actionType: String(opts.actionType),
+        };
+        if (opts.policyFile)
+            body.policyFile = String(opts.policyFile);
+        if (opts.policyVersion)
+            body.policyVersion = String(opts.policyVersion);
+        if (opts.gitSha)
+            body.gitSha = String(opts.gitSha);
+        if (opts.actorType)
+            body.actorType = String(opts.actorType);
+        if (opts.userId)
+            body.userId = String(opts.userId);
+        if (opts.branchName)
+            body.branchName = String(opts.branchName);
+        if (opts.entityType)
+            body.entityType = String(opts.entityType);
+        if (opts.entityIdentity)
+            body.entityIdentity = String(opts.entityIdentity);
+        if (opts.testJson)
+            body.test = JSON.parse(String(opts.testJson));
+        if (opts.detailJson)
+            body.detailJson = String(opts.detailJson);
+        const merged = mergeBodies(body, opts.jsonInput);
+        console.log(await runTool("report-agent-action", merged, { postMcp }));
+    });
+    program
+        .command("get-last-run-workflow-detail")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-last-run-workflow-detail").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--workflow-id <id>", "Catalog workflow id")
+        .option("--branch-name <name>", "Optional branch filter (omit for any branch)")
+        .option("--user-id <id>", "Optional per-user last run")
+        .action(async (opts) => {
+        const body = { workflowId: String(opts.workflowId) };
+        if (opts.branchName)
+            body.branchName = String(opts.branchName);
+        if (opts.userId)
+            body.userId = String(opts.userId);
+        const merged = mergeBodies(body, opts.jsonInput);
+        console.log(await runTool("get-last-run-workflow-detail", merged, { postMcp }));
+    });
+    for (const kebab of [
+        "list-workflow-executions",
+        "get-workflow-execution",
+        "get-policy",
+        "list-policies",
+        "list-workflow-catalog",
+    ]) {
+        program
+            .command(kebab)
+            .description(TOOL_DEFINITIONS.find((t) => t.kebab === kebab).description)
+            .addOption(jsonInputOption())
+            .action(async (opts) => {
+            const merged = mergeBodies({}, opts.jsonInput);
+            console.log(await runTool(kebab, merged, { postMcp }));
+        });
+    }
     program.on("--help", () => {
         /* default */
     });

package/dist/core/schemas.d.ts

@@ -1015,3 +1015,86 @@ export declare const reportRequirementQualityFindingsInput: z.ZodObject<{
     subjectEntityId: z.ZodOptional<z.ZodString>;
     ordinalId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
+export declare const agentActorTypeSchema: z.ZodEnum<{
+    LOCAL_AGENT: "LOCAL_AGENT";
+    CLOUD_AGENT: "CLOUD_AGENT";
+    "local-agent": "local-agent";
+    "cloud-agent": "cloud-agent";
+}>;
+export declare const agentActionTypeSchema: z.ZodEnum<{
+    failed: "failed";
+    CREATED: "CREATED";
+    UPDATED: "UPDATED";
+    DELETED: "DELETED";
+    ANALYZED: "ANALYZED";
+    ACTION_COMPLETED: "ACTION_COMPLETED";
+    ACTION_FAILED: "ACTION_FAILED";
+    created: "created";
+    updated: "updated";
+    deleted: "deleted";
+    analyzed: "analyzed";
+    completed: "completed";
+    action_completed: "action_completed";
+    action_failed: "action_failed";
+}>;
+export declare const reportAgentActionInput: z.ZodObject<{
+    workflowId: z.ZodString;
+    workflowExecutionId: z.ZodString;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    entityType: z.ZodOptional<z.ZodString>;
+    entityIdentity: z.ZodOptional<z.ZodString>;
+    test: z.ZodOptional<z.ZodObject<{
+        folderPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fileName: z.ZodString;
+        testSuite: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        testName: z.ZodString;
+    }, z.core.$strip>>;
+    actionType: z.ZodEnum<{
+        failed: "failed";
+        CREATED: "CREATED";
+        UPDATED: "UPDATED";
+        DELETED: "DELETED";
+        ANALYZED: "ANALYZED";
+        ACTION_COMPLETED: "ACTION_COMPLETED";
+        ACTION_FAILED: "ACTION_FAILED";
+        created: "created";
+        updated: "updated";
+        deleted: "deleted";
+        analyzed: "analyzed";
+        completed: "completed";
+        action_completed: "action_completed";
+        action_failed: "action_failed";
+    }>;
+    detailJson: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const getLastRunWorkflowDetailInput: z.ZodObject<{
+    workflowId: z.ZodString;
+    branchName: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const listWorkflowExecutionsInput: z.ZodObject<{
+    workflowId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const getWorkflowExecutionInput: z.ZodObject<{
+    workflowExecutionId: z.ZodString;
+    includeActions: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const getPolicyInput: z.ZodObject<{
+    policyFileName: z.ZodString;
+}, z.core.$strip>;
+export declare const listPoliciesInput: z.ZodObject<{
+    workflowId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const listWorkflowCatalogInput: z.ZodObject<{}, z.core.$strip>;

package/dist/core/schemas.js

@@ -500,3 +500,68 @@ export const reportRequirementQualityFindingsInput = z
         });
     }
 });
+export const agentActorTypeSchema = z.enum(["LOCAL_AGENT", "CLOUD_AGENT", "local-agent", "cloud-agent"]);
+export const agentActionTypeSchema = z.enum([
+    "CREATED",
+    "UPDATED",
+    "DELETED",
+    "ANALYZED",
+    "ACTION_COMPLETED",
+    "ACTION_FAILED",
+    "created",
+    "updated",
+    "deleted",
+    "analyzed",
+    "completed",
+    "failed",
+    "action_completed",
+    "action_failed",
+]);
+export const reportAgentActionInput = z
+    .object({
+    workflowId: z.string().min(1),
+    workflowExecutionId: z.string().min(1),
+    policyFile: z.string().optional(),
+    policyVersion: z.string().optional(),
+    gitSha: z.string().optional(),
+    actorType: agentActorTypeSchema.optional(),
+    userId: z.string().optional(),
+    branchName: z.string().optional(),
+    entityType: z.string().optional(),
+    /** Project-scoped ordinal id (or explicitly provided execution/batch id). Mutually exclusive with `test`. */
+    entityIdentity: z.string().optional(),
+    /** SmartTest TestLocator. Mutually exclusive with `entityIdentity`. */
+    test: testLocatorSchema.optional(),
+    actionType: agentActionTypeSchema,
+    detailJson: z.string().optional(),
+})
+    .superRefine((val, ctx) => {
+    if (val.test && val.entityIdentity) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Provide either test (TestLocator) or entityIdentity (ordinal), not both",
+            path: ["test"],
+        });
+    }
+});
+export const getLastRunWorkflowDetailInput = z.object({
+    workflowId: z.string().min(1),
+    branchName: z.string().optional(),
+    userId: z.string().optional(),
+});
+export const listWorkflowExecutionsInput = z.object({
+    workflowId: z.string().optional(),
+    limit: z.coerce.number().int().positive().max(200).optional(),
+    offset: z.coerce.number().int().nonnegative().optional(),
+});
+export const getWorkflowExecutionInput = z.object({
+    workflowExecutionId: z.string().min(1),
+    includeActions: z.boolean().optional(),
+});
+export const getPolicyInput = z.object({
+    policyFileName: z.string().min(1),
+});
+export const listPoliciesInput = z.object({
+    workflowId: z.string().optional(),
+});
+export const listWorkflowCatalogInput = z.object({});

package/dist/core/tools.js

@@ -776,6 +776,128 @@ export const TOOL_DEFINITIONS = [
             return postMcp("/api/mcp/report_requirement_quality_findings", { report });
         },
     },
+    {
+        kebab: "report-agent-action",
+        description: "Report a mutating agent action under a stable workflow-execution-id (ULID). " +
+            "First call for an id creates the workflow_executions row; later calls append agent_actions. " +
+            "Identity: pass `test` (TestLocator: folderPath/fileName/testSuite/testName) for SmartTests, " +
+            "or `entityIdentity` as a project-scoped ordinal id for stories/scenarios/issues " +
+            "(or an execution/batch id only when the prompt explicitly provided it). Do not use platform UUIDs.",
+        inputSchema: S.reportAgentActionInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const actorRaw = (a.actorType ?? "local-agent").toString();
+            const actorType = actorRaw.toUpperCase().replace(/-/g, "_") === "CLOUD_AGENT" ? "CLOUD_AGENT" : "LOCAL_AGENT";
+            const actionNorm = a.actionType.toString().toUpperCase().replace(/-/g, "_");
+            let actionType = actionNorm;
+            if (actionNorm === "COMPLETED" || actionNorm === "ACTION_COMPLETED") {
+                actionType = "ACTION_COMPLETED";
+            }
+            else if (actionNorm === "FAILED" || actionNorm === "ACTION_FAILED") {
+                actionType = "ACTION_FAILED";
+            }
+            const body = {
+                workflowId: a.workflowId,
+                workflowExecutionId: a.workflowExecutionId,
+                actionType,
+                actorType,
+            };
+            if (a.policyFile)
+                body.policyFile = a.policyFile;
+            if (a.policyVersion)
+                body.policyVersion = a.policyVersion;
+            if (a.gitSha)
+                body.gitSha = a.gitSha;
+            if (a.userId)
+                body.userId = a.userId;
+            else if (process.env.TESTCHIMP_USER_ID)
+                body.userId = process.env.TESTCHIMP_USER_ID;
+            if (a.branchName)
+                body.branchName = a.branchName;
+            if (a.entityType)
+                body.entityType = a.entityType;
+            if (a.test) {
+                body.test = a.test;
+            }
+            else if (a.entityIdentity) {
+                body.entityIdentity = a.entityIdentity;
+            }
+            if (a.detailJson)
+                body.detailJson = a.detailJson;
+            return postMcp("/api/mcp/report_agent_action", body);
+        },
+    },
+    {
+        kebab: "get-last-run-workflow-detail",
+        description: "Fetch the last workflow execution for a workflow-id on a branch (optional userId for per-user last run). " +
+            "Used for since-last-run scoping.",
+        inputSchema: S.getLastRunWorkflowDetailInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {
+                workflowId: a.workflowId,
+                branchName: a.branchName,
+            };
+            if (a.userId)
+                body.userId = a.userId;
+            return postMcp("/api/mcp/get_last_run_workflow_detail", body);
+        },
+    },
+    {
+        kebab: "list-workflow-executions",
+        description: "List recent workflow executions for the project, optionally filtered by workflowId.",
+        inputSchema: S.listWorkflowExecutionsInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {};
+            if (a.workflowId)
+                body.workflowId = a.workflowId;
+            if (a.limit != null)
+                body.limit = a.limit;
+            if (a.offset != null)
+                body.offset = a.offset;
+            return postMcp("/api/mcp/list_workflow_executions", body);
+        },
+    },
+    {
+        kebab: "get-workflow-execution",
+        description: "Get a workflow execution by id; pass includeActions=true for the action timeline.",
+        inputSchema: S.getWorkflowExecutionInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/get_workflow_execution", {
+                workflowExecutionId: a.workflowExecutionId,
+                includeActions: a.includeActions ?? true,
+            });
+        },
+    },
+    {
+        kebab: "get-policy",
+        description: "Fetch a workflow policy file by name (e.g. run-qa.policy.md) from the platform POLICY_FILE store.",
+        inputSchema: S.getPolicyInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/get_policy", { policyFileName: a.policyFileName });
+        },
+    },
+    {
+        kebab: "list-policies",
+        description: "List policy files for an optional workflow-id. Marks isDefault when filename is <workflow-id>.policy.md.",
+        inputSchema: S.listPoliciesInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {};
+            if (a.workflowId)
+                body.workflowId = a.workflowId;
+            return postMcp("/api/mcp/list_policies", body);
+        },
+    },
+    {
+        kebab: "list-workflow-catalog",
+        description: "List supported TestChimp workflows with Active / Disabled / Missing Config status for the project.",
+        inputSchema: S.listWorkflowCatalogInput,
+        execute: async (_args, { postMcp }) => postMcp("/api/mcp/list_workflow_catalog", {}),
+    },
 ];
 const TOOL_BY_KEBAB = new Map(TOOL_DEFINITIONS.map((t) => [t.kebab, t]));
 export function getToolDefinition(kebab) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testchimp/cli",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "TestChimp CLI and MCP server — coverage, plans, EaaS, TrueCoverage (calls /api/mcp/*)",
   "type": "module",
   "main": "dist/bin/testchimp.js",