@withgauge/cli 0.12.0 → 0.12.1

package/README.md

@@ -215,6 +215,24 @@ Edit a skill with `--edit-skill <versionId> --skill-dir <path>`: the directory
 holds the complete bundle, `SKILL.md` included. `trials template --kind <kind>`
 prints a skeleton for the `--file` form.
 
+A chat-guided round, such as a CLI change, goes through preview and save. Save
+replaces the pending drafts, so it can fix a draft that is wrong:
+
+```sh
+gauge optimizations authoring cl_1 > context.json   # revision, CLI targets, invocations
+gauge optimizations invocation cl_1 inv_1           # one recorded baseline invocation
+gauge optimizations cli-change cl_1 --file change.json > bundle.json
+# round.json: {"revision": "...", "trials": [{"trial": {"title": "...",
+#   "lever": "CLI", "intervention": {"kind": "CLI_INTERVENTION", "after": <bundle.json>}}}]}
+gauge optimizations round preview cl_1 --file round.json   # prints previewDigest
+gauge optimizations round save cl_1 --file round.json --digest <previewDigest>
+gauge optimizations trials remove cl_1 R1.2 --yes    # drop one draft
+gauge optimizations launch cl_1 --yes
+```
+
+A `completeOutput` literal matcher is an exact, case-sensitive match. Copy it
+from the recorded command output.
+
 Every detail carries `nextAction` — `START`, `WAIT`, `AUTHOR_TRIAL`,
 `LAUNCH_ROUND`, `ADOPT`, `RESUME`, or `NONE`. Read it (`get -o json`) instead of
 inferring whose turn it is from round and trial statuses. `watch` exits `4` when

package/dist/index.js

@@ -2568,9 +2568,6 @@ var meResponseSchema = z27.object({
 // ../packages/api-schemas/src/optimizations.ts
 import { z as z31 } from "zod";
 
-// ../packages/api-schemas/src/climb.ts
-import { z as z30 } from "zod";
-
 // ../packages/api-schemas/src/cli-interventions.ts
 import { z as z28 } from "zod";
 var digest = z28.string().regex(/^[a-f0-9]{64}$/);
@@ -2598,12 +2595,47 @@ var cliLaunchFormSchema = z28.enum([
   "execveat-path",
   "execveat-fd"
 ]);
+var cliObservationReasonSchema = z28.enum([
+  "eligible",
+  "other-target",
+  "other-command",
+  "selector-mismatch",
+  "unknown-command",
+  "identity-unresolved",
+  "artifact-mismatch",
+  "runtime-mismatch",
+  "launch-form",
+  "io-profile",
+  "operation-profile",
+  "descriptor-lifetime"
+]);
 var cliIoProfileSchema = z28.enum([
   "pipes",
   "redirected",
   "shared-descriptor",
   "pty"
 ]);
+var cliObservationSchema = z28.object({
+  invocationId: z28.string().regex(/^[a-f0-9]{32}$/),
+  targetId: token,
+  commandId: token.nullable(),
+  entrypointSha256: digest,
+  runtimeSha256: digest.nullable(),
+  launchForm: cliLaunchFormSchema.nullable(),
+  ioProfile: cliIoProfileSchema.nullable(),
+  reason: cliObservationReasonSchema
+});
+var cliCoverageSchema = z28.object({
+  attempt: z28.number().int().nonnegative(),
+  observedInvocationCount: z28.number().int().nonnegative().nullable(),
+  invocationCount: z28.number().int().nonnegative(),
+  appliedInvocationCount: z28.number().int().nonnegative(),
+  incompleteCount: z28.number().int().nonnegative(),
+  unsupportedCount: z28.number().int().nonnegative(),
+  instrumentationFailed: z28.boolean(),
+  observations: z28.array(cliObservationSchema),
+  unsupportedDiagnostics: z28.array(z28.string())
+});
 var cliOperationKindSchema = z28.enum([
   "ensureOption",
   "replaceOption",
@@ -2866,12 +2898,14 @@ var baselineInvocationSchema = z28.object({
   artifactSha256: digest.nullable(),
   entrypointSha256: digest,
   engineSha256: digest.optional(),
+  runtimeSha256: digest.optional(),
   launchForm: cliLaunchFormSchema,
   ioProfile: cliIoProfileSchema,
   recordFiles: z28.array(cliBaselineRecordFileSchema).max(50).default([])
 }).strict();
 var cliInterventionSchema = z28.object({
   schemaVersion: z28.union([z28.literal(1), z28.literal(2)]),
+  identityPolicy: z28.literal("artifact").optional(),
   engineVersion: token,
   engineSha256: digest.nullable(),
   bundleSha256: digest,
@@ -2904,6 +2938,13 @@ var cliInterventionSchema = z28.object({
   const fail = (path2, message) => ctx.addIssue({ code: "custom", path: path2, message });
   if (bundle.schemaVersion !== bundle.catalog.version)
     fail(["schemaVersion"], "Bundle and catalog schema versions differ");
+  if (bundle.identityPolicy && bundle.schemaVersion !== 2)
+    fail(["identityPolicy"], "Artifact identity requires schema version 2");
+  if (bundle.identityPolicy && bundle.baselineInvocations.some((row2) => !row2.runtimeSha256))
+    fail(
+      ["baselineInvocations"],
+      "Artifact identity requires the recorded runtime bytes"
+    );
   if (!bundle.engineSha256 && (bundle.schemaVersion === 1 || bundle.mode !== "record"))
     fail(["engineSha256"], "A trial must pin the recorded engine bytes");
   if (!bundle.catalog.targets.length)
@@ -3095,6 +3136,9 @@ var cliTrialChangeSchema = z28.object({
   shippingIntent: cliInterventionSchema.shape.shippingIntent.unwrap()
 }).strict();
 
+// ../packages/api-schemas/src/climb.ts
+import { z as z30 } from "zod";
+
 // ../packages/api-schemas/src/climb-kinds.ts
 var LEVER_KINDS = [
   "DOCS",
@@ -3536,6 +3580,7 @@ var diagnosisSchema = z31.object({
 var trialRunSchema = z31.object({
   id: z31.string(),
   status: z31.string(),
+  cliCoverage: cliCoverageSchema.nullable().optional(),
   passed: z31.boolean().nullable(),
   criteria: z31.array(
     z31.object({ name: z31.string(), passed: z31.boolean(), reasoning: z31.string() })
@@ -4013,11 +4058,18 @@ var runPlanSchema = z39.object({
   resources: z39.array(runPlanResourceSchema).default([]),
   /** Server-populated context retained across deferred preparation. */
   launch: z39.object({
-    origin: z39.object({
-      initiator: z39.literal("API"),
-      userId: z39.string().min(1),
-      email: z39.string().nullable()
-    }).strict(),
+    origin: z39.discriminatedUnion("initiator", [
+      z39.object({
+        initiator: z39.literal("API"),
+        userId: z39.string().min(1),
+        email: z39.string().nullable()
+      }).strict(),
+      z39.object({
+        initiator: z39.literal("GITHUB"),
+        userId: z39.null(),
+        email: z39.null()
+      }).strict()
+    ]),
     funding: z39.enum(["ORG", "PLATFORM"]),
     queueClass: z39.literal("INTERACTIVE")
   }).strict().optional(),
@@ -4028,7 +4080,7 @@ var runPlanSchema = z39.object({
       digest: z39.string().min(1),
       /** File submissions are asserted by the caller until server-side
        * committed-byte fetching is available. */
-      verification: z39.literal("SUBMITTED_UNVERIFIED").optional()
+      verification: z39.enum(["SUBMITTED_UNVERIFIED", "GITHUB_VERIFIED"]).optional()
     }).optional(),
     liveDependencies: z39.array(
       z39.object({
@@ -4158,7 +4210,7 @@ var runDefinitionSubmissionSchema = z40.object({
     repoUrl: uncredentialedRepoUrlSchema,
     commit: z40.string().regex(/^[a-f0-9]{40}$/i),
     digest: z40.string().regex(/^sha256:[a-f0-9]{64}$/),
-    verification: z40.literal("SUBMITTED_UNVERIFIED")
+    verification: z40.enum(["SUBMITTED_UNVERIFIED", "GITHUB_VERIFIED"])
   }).strict(),
   resources: z40.array(preparedDirectoryResourceSchema).max(1).default([]),
   cases: z40.array(runDefinitionCaseSchema).min(1)
@@ -4200,6 +4252,13 @@ var runDefinitionSubmissionSchema = z40.object({
       });
   }
 });
+var runDefinitionPublicSubmissionSchema = runDefinitionSubmissionSchema.refine(
+  (definition) => definition.source.verification === "SUBMITTED_UNVERIFIED",
+  {
+    path: ["source", "verification"],
+    message: "Only the GitHub App may verify committed bytes"
+  }
+);
 var runDefinitionPlanResponseSchema = z40.object({
   source: runDefinitionSubmissionSchema.shape.source,
   measurementMode: z40.literal("AGENT_EXPERIENCE"),
@@ -6347,9 +6406,112 @@ function cadenceLabel(cadence) {
 
 // src/lib/runDefinitionFiles.ts
 import { execFileSync } from "child_process";
-import { createHash as createHash2 } from "crypto";
 import { isAbsolute, relative, resolve, sep } from "path";
+
+// ../packages/api-schemas/src/compileRunDefinition.ts
+import { createHash as createHash2 } from "crypto";
 import { parseDocument } from "yaml";
+function utf8(bytes, path2) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error(`${path2} is not UTF-8 text`);
+  }
+}
+function markdownCase(path2, bytes) {
+  const source = utf8(bytes, path2);
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(source);
+  if (!match)
+    throw new Error(`${path2}: expected YAML frontmatter between --- lines`);
+  const document = parseDocument(match[1], { uniqueKeys: true });
+  if (document.errors.length)
+    throw new Error(
+      `${path2}: ${document.errors.map((error) => error.message).join("; ")}`
+    );
+  const parsed = runDefinitionFrontmatterSchema.safeParse(document.toJS());
+  if (!parsed.success) throw new Error(`${path2}: ${parsed.error.message}`);
+  const prompt = match[2].trim();
+  if (!prompt) throw new Error(`${path2}: Markdown body is empty`);
+  return { path: path2, prompt, ...parsed.data };
+}
+function compileRunDefinitionFromBlobs(input) {
+  if (!uncredentialedRepoUrlSchema.safeParse(input.repoUrl).success)
+    throw new Error("Git origin must not contain embedded credentials");
+  if (!/^[a-f0-9]{40}$/i.test(input.commit))
+    throw new Error("Expected a full Git commit SHA");
+  if (input.casePaths.length === 0)
+    throw new Error("At least one Markdown case is required");
+  if (new Set(input.casePaths).size !== input.casePaths.length)
+    throw new Error("Case paths must be unique");
+  const configBytes = input.blobs.get("gauge.json");
+  let config;
+  if (configBytes) {
+    try {
+      config = runDefinitionFileConfigSchema.parse(
+        JSON.parse(utf8(configBytes, "gauge.json"))
+      );
+    } catch (error) {
+      throw new Error(
+        `gauge.json: ${error instanceof Error ? error.message : error}`
+      );
+    }
+  }
+  const conventionalPrepare = input.blobs.has(".gauge/prepare.sh");
+  if (config?.product && conventionalPrepare)
+    throw new Error(
+      "gauge.json: product and .gauge/prepare.sh are alternatives"
+    );
+  const prepare = config?.prepare ?? (conventionalPrepare ? "bash .gauge/prepare.sh" : void 0);
+  const preparation = config?.product ?? (prepare ? { run: prepare } : void 0);
+  if (config?.install && !prepare)
+    throw new Error("gauge.json: install requires prepare");
+  if (preparation && !input.repoUrl.startsWith("https://"))
+    throw new Error("Project preparation requires a public HTTPS Git origin");
+  const cases = input.casePaths.map((path2) => {
+    const bytes = input.blobs.get(path2);
+    if (!path2.endsWith(".md") || !bytes)
+      throw new Error(`Missing committed Markdown case: ${path2}`);
+    return markdownCase(path2, bytes);
+  });
+  const hash = createHash2("sha256");
+  hash.update("gauge-run-definition-v1\0");
+  for (const [path2, bytes] of [...input.blobs.entries()].sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  )) {
+    hash.update(path2);
+    hash.update("\0");
+    hash.update(String(bytes.length));
+    hash.update("\0");
+    hash.update(bytes);
+    hash.update("\0");
+  }
+  const submission = runDefinitionSubmissionSchema.parse({
+    version: 1,
+    source: {
+      repoUrl: input.repoUrl,
+      commit: input.commit,
+      digest: `sha256:${hash.digest("hex")}`,
+      verification: input.verification
+    },
+    resources: preparation ? [
+      {
+        name: "project",
+        type: "prepared-directory",
+        source: {
+          type: "git-checkout",
+          repoUrl: input.repoUrl,
+          commit: input.commit
+        },
+        prepare: preparation,
+        ...config?.install ? { install: config.install } : {}
+      }
+    ] : [],
+    cases
+  });
+  return { definition: submission, org: config?.org, github: config?.github };
+}
+
+// src/lib/runDefinitionFiles.ts
 function git(cwd, args) {
   try {
     return execFileSync("git", args, {
@@ -6366,39 +6528,6 @@ function git(cwd, args) {
 function committedBlob(root, commit, path2) {
   return git(root, ["show", `${commit}:${path2}`]);
 }
-function decode(blob, path2) {
-  try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(blob);
-  } catch {
-    throw new CliError("usage", `${path2} is not UTF-8 text`);
-  }
-}
-function parseYaml(text, path2) {
-  const document = parseDocument(text, { uniqueKeys: true });
-  if (document.errors.length) {
-    throw new CliError(
-      "usage",
-      `${path2}: ${document.errors.map((error) => error.message).join("; ")}`
-    );
-  }
-  return document.toJS();
-}
-function caseFromMarkdown(path2, source) {
-  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(source);
-  if (!match)
-    throw new CliError(
-      "usage",
-      `${path2}: expected YAML frontmatter between --- lines`
-    );
-  const parsed = runDefinitionFrontmatterSchema.safeParse(
-    parseYaml(match[1], path2)
-  );
-  if (!parsed.success)
-    throw new CliError("usage", `${path2}: ${parsed.error.message}`);
-  const prompt = match[2].trim();
-  if (!prompt) throw new CliError("usage", `${path2}: Markdown body is empty`);
-  return { path: path2, prompt, ...parsed.data };
-}
 function relativeGitPath(root, cwd, input) {
   if (!input || input.includes("\0") || /[*?[\]{}]/.test(input))
     throw new CliError("usage", `expected an explicit case path: ${input}`);
@@ -6436,83 +6565,34 @@ function loadCommittedRunDefinitionWithContext(files, cwd = process.cwd()) {
   const paths = files.map((file) => relativeGitPath(root, cwd, file));
   if (new Set(paths).size !== paths.length)
     throw new CliError("usage", "case paths must be unique");
-  const blobs = [];
-  let config;
+  const blobs = /* @__PURE__ */ new Map();
   const hasConfig = git(root, ["ls-tree", "--name-only", commit, "--", "gauge.json"]).toString("utf8").trim() === "gauge.json";
   if (hasConfig) {
-    try {
-      const bytes = committedBlob(root, commit, "gauge.json");
-      blobs.push({ path: "gauge.json", bytes });
-      config = runDefinitionFileConfigSchema.parse(
-        JSON.parse(decode(bytes, "gauge.json"))
-      );
-    } catch (error) {
-      throw new CliError(
-        "usage",
-        `gauge.json: ${error instanceof Error ? error.message : error}`
-      );
-    }
+    blobs.set("gauge.json", committedBlob(root, commit, "gauge.json"));
   }
   const hasConventionalPrepare = git(root, ["ls-tree", "--name-only", commit, "--", ".gauge/prepare.sh"]).toString("utf8").trim() === ".gauge/prepare.sh";
   if (hasConventionalPrepare) {
-    blobs.push({
-      path: ".gauge/prepare.sh",
-      bytes: committedBlob(root, commit, ".gauge/prepare.sh")
-    });
-  }
-  if (config?.product && hasConventionalPrepare)
-    throw new CliError(
-      "usage",
-      "gauge.json: product and .gauge/prepare.sh are alternatives"
+    blobs.set(
+      ".gauge/prepare.sh",
+      committedBlob(root, commit, ".gauge/prepare.sh")
     );
-  const prepare = config?.prepare ?? (hasConventionalPrepare ? "bash .gauge/prepare.sh" : void 0);
-  const preparation = config?.product ?? (prepare ? { run: prepare } : void 0);
-  if (config?.install && !prepare)
-    throw new CliError("usage", "gauge.json: install requires prepare");
-  if (preparation && !repoUrl.startsWith("https://"))
-    throw new CliError(
-      "usage",
-      "Project preparation requires a public HTTPS Git origin"
-    );
-  const cases = paths.map((path2) => {
-    const bytes = committedBlob(root, commit, path2);
-    blobs.push({ path: path2, bytes });
-    return caseFromMarkdown(path2, decode(bytes, path2));
-  });
-  const hash = createHash2("sha256");
-  hash.update("gauge-run-definition-v1\0");
-  for (const entry of blobs.sort(
-    (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0
-  )) {
-    hash.update(entry.path);
-    hash.update("\0");
-    hash.update(String(entry.bytes.length));
-    hash.update("\0");
-    hash.update(entry.bytes);
-    hash.update("\0");
   }
-  const submission = runDefinitionSubmissionSchema.safeParse({
-    version: 1,
-    source: {
+  for (const path2 of paths) blobs.set(path2, committedBlob(root, commit, path2));
+  try {
+    const result = compileRunDefinitionFromBlobs({
       repoUrl,
       commit,
-      digest: `sha256:${hash.digest("hex")}`,
+      casePaths: paths,
+      blobs,
       verification: "SUBMITTED_UNVERIFIED"
-    },
-    resources: preparation ? [
-      {
-        name: "project",
-        type: "prepared-directory",
-        source: { type: "git-checkout", repoUrl, commit },
-        prepare: preparation,
-        ...config?.install ? { install: config.install } : {}
-      }
-    ] : [],
-    cases
-  });
-  if (!submission.success)
-    throw new CliError("usage", submission.error.message);
-  return { definition: submission.data, org: config?.org };
+    });
+    return { definition: result.definition, org: result.org };
+  } catch (error) {
+    throw new CliError(
+      "usage",
+      error instanceof Error ? error.message : String(error)
+    );
+  }
 }
 
 // src/lib/staff.ts
@@ -8269,6 +8349,18 @@ function printChange(content) {
     console.log(doc.after || "(empty)");
   }
 }
+function printRoundPreview(preview) {
+  for (const trial of preview.trials) {
+    console.log(trial.title);
+    for (const change of trial.changes ?? []) {
+      console.log(`=== ${change.path}`);
+      console.log(change.hunks);
+    }
+    for (const path2 of trial.droppedFiles ?? [])
+      console.log(`  ${path2}: dropped`);
+  }
+  console.log(`previewDigest ${preview.previewDigest}`);
+}
 function printEstimate(e) {
   console.log(
     `plan:      ${e.sampleCount} session${e.sampleCount === 1 ? "" : "s"} per trial \xD7 up to ${e.maxRounds} rounds`
@@ -8644,7 +8736,7 @@ function register19(program2) {
       let last = "";
       for (; ; ) {
         const detail = await client.get(itemPath2(org, id));
-        const trials2 = detail.rounds.flatMap((round) => round.trials);
+        const trials2 = detail.rounds.flatMap((round2) => round2.trials);
         const line = `${detail.status}${detail.stopReason ? ` (${detail.stopReason})` : ""} \xB7 round ${detail.round}/${detail.maxRounds} \xB7 ${pct(detail.before)} \u2192 ${pct(detail.after)} \xB7 ${detail.creditsSpent} credits spent \xB7 ${trials2.filter((t) => t.status === "RUNNING").map((t) => t.key).join(",") || "idle"}`;
         if (line !== last) {
           last = line;
@@ -8661,6 +8753,60 @@ function register19(program2) {
       }
     }
   );
+  group.command("authoring <id>").description(
+    "What the next round may change: kinds, CLI targets and commands, baseline invocations, revision"
+  ).action(async (id, _opts, cmd) => {
+    printJson(
+      await createClient().get(`${itemPath2(resolveOrg(cmd), id)}/authoring`)
+    );
+  });
+  group.command("invocation <id> <invocationId>").description(
+    "One baseline CLI invocation from `authoring`, with its recorded command evidence"
+  ).action(
+    async (id, invocationId, _opts, cmd) => {
+      printJson(
+        await createClient().get(
+          `${itemPath2(resolveOrg(cmd), id)}/authoring/target`,
+          { cliInvocationId: invocationId }
+        )
+      );
+    }
+  );
+  group.command("cli-change <id>").description(
+    "Build a CLI_INTERVENTION bundle from {targetId, commandId, selector, operations, shippingIntent}; use the output as intervention.after in a round file. Saves nothing"
+  ).requiredOption("--file <path>", "the change JSON; '-' for stdin").action(async (id, opts, cmd) => {
+    printJson(
+      await createClient().post(
+        `${itemPath2(resolveOrg(cmd), id)}/cli-changes`,
+        readObject(opts.file)
+      )
+    );
+  });
+  const round = group.command("round").description(
+    "Preview and save the round waiting to launch. A round file is {revision, trials: [{trial: {title, hypothesis, lever, intervention}, files?}]}; revision comes from `authoring`"
+  );
+  round.command("preview <id>").description("Validate a round file and print its diff and previewDigest").requiredOption("--file <path>", "the round JSON; '-' for stdin").action(async (id, opts, cmd) => {
+    const preview = await createClient().post(
+      `${itemPath2(resolveOrg(cmd), id)}/rounds/current/preview`,
+      readObject(opts.file)
+    );
+    if (resolveOutput(cmd) === "json") printJson(preview);
+    else printRoundPreview(preview);
+  });
+  round.command("save <id>").description(
+    "Save a previewed round as drafts, replacing every pending draft. Never launches"
+  ).requiredOption("--file <path>", "the round JSON you previewed").requiredOption("--digest <digest>", "previewDigest from `round preview`").action(
+    async (id, opts, cmd) => {
+      const result = await createClient().put(
+        `${itemPath2(resolveOrg(cmd), id)}/rounds/current`,
+        { ...readObject(opts.file), previewDigest: opts.digest }
+      );
+      if (resolveOutput(cmd) === "json") printJson(result);
+      else
+        for (const trial of result.trials)
+          console.log(`Saved ${trial.key} "${trial.title}"`);
+    }
+  );
   const trials = group.command("trials").description("List, author, and run trials");
   trials.command("list <id>").description("Every trial of an optimization with score and verdict").action(async (id, _opts, cmd) => {
     const org = resolveOrg(cmd);
@@ -8732,6 +8878,16 @@ function register19(program2) {
         );
     }
   );
+  trials.command("remove <id> <trialId>").description("Drop one draft trial from the round waiting to launch").option("--yes", "skip the confirmation").action(
+    async (id, trialId, opts, cmd) => {
+      await confirmOrAbort(`Remove draft ${trialId} from ${id}?`, opts.yes);
+      const detail = await createClient().delete(
+        trialPath(resolveOrg(cmd), id, trialId)
+      );
+      if (resolveOutput(cmd) === "json") printJson(detail);
+      else console.log(`Removed ${trialId}.`);
+    }
+  );
   group.command("trial <id> <trialId>").description("One trial by id or key (B0, R1.1, \u2026) with its sessions").action(
     async (id, trialId, _opts, cmd) => {
       const org = resolveOrg(cmd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withgauge/cli",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Gauge customer CLI — Agent Preference, evals, runs, and organization settings over the Gauge API",
   "private": false,
   "author": "Gauge <support@withgauge.com> (https://withgauge.com)",