Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

12.9 KB
Raw Blame
/**
 * Parameters in a skill's steps (design 4.5 step 10): the values that change
 * from one run to the next (a version, a commit, a PR, a port, a branch, a
 * date, and a token that differed from the last run of the same job) become
 * `{name}` with a default where one makes sense, so the next run fills them
 * instead of replaying last time's literal.
 */
import { test } from "node:test";
import assert from "node:assert/strict";
import { STABLE_BRANCHES, fillParams, findParams, metaToParams, paramsToMeta, resolveParams } from "../src/skills/params.js";

const find = (cmds: string[], prompt = {}, extra: { prior?: string[] | null; check?: string } = {}) => findParams(cmds, { prompt, ...extra });

test("version: one name per value, the v kept, inside a .tgz too", () => {
  const r = find(['git tag v0.22.1 -m "release; notes" && git push origin v0.22.1', "npm publish trailhq-trail-code-0.22.1.tgz --access public"]);
  assert.deepEqual(r.cmds, ['git tag v{version} -m "release; notes" && git push origin v{version}', "npm publish trailhq-trail-code-{version}.tgz --access public"]);
  assert.deepEqual(r.params, [{ name: "version", shape: "version", seen: ["0.22.1"] }]);
  // A pre-release version stops before .tgz.
  assert.equal(find(["npm publish acme-cli-1.4.2-beta.1.tgz"]).cmds[0], "npm publish acme-cli-{version}.tgz");
});

test("version: the one the person typed is {version}, other values {version_2}", () => {
  const r = find(["npm version 1.4.2 && npm publish", "npm view [email protected] version"], { version: "1.4.2" });
  assert.deepEqual(r.cmds, ["npm version {version} && npm publish", "npm view acme-cli@{version_2} version"]);
  assert.deepEqual(r.params.map((p) => [p.name, p.seen]), [["version", ["1.4.2"]], ["version_2", ["1.4.1"]]]);
  // Without a typed one, the first value seen is {version}.
  assert.deepEqual(find(["npm view [email protected] version"], { version: "2.0.0" }).cmds, ["npm view acme-cli@{version} version"]);
});

test("version: not an install pin, nvm, node@ / python@ / go@, or an address", () => {
  for (const cmd of [
    "npm i -g [email protected]",
    "npm install [email protected] --save",
    "pnpm add [email protected]",
    "yarn add [email protected]",
    "nvm use 20.11.0",
    "npx [email protected] --version",
    "uvx [email protected] -V",
    "go run [email protected]",
    "curl -s http://10.1.2.3/status",
    "ping 10.0.0.1",
  ]) assert.deepEqual(find([cmd]).cmds, [cmd], cmd);
  // An install pin stays, a later publish of the same project's version is still a param.
  assert.deepEqual(find(["npm i [email protected] && npm publish acme-cli-2.0.1.tgz"]).cmds, ["npm i [email protected] && npm publish acme-cli-{version}.tgz"]);
});

test("sha: before :refs/, after commits/, in merge-base --is-ancestor, as a git argument; every occurrence the same name", () => {
  const r = find([
    "git push [email protected]:acme/storefront.git 4e1c9a2:refs/heads/beta",
    "git merge-base --is-ancestor origin/prod 4e1c9a2",
    "git push [email protected]:acme/storefront.git 4e1c9a2:refs/heads/prod",
  ], {}, { check: "gh api repos/acme/storefront/commits/4e1c9a2/statuses --jq '.[0].state'" });
  assert.deepEqual(r.cmds, [
    "git push [email protected]:acme/storefront.git {sha}:refs/heads/beta",
    "git merge-base --is-ancestor origin/prod {sha}",
    "git push [email protected]:acme/storefront.git {sha}:refs/heads/prod",
  ]);
  assert.equal(r.check, "gh api repos/acme/storefront/commits/{sha}/statuses --jq '.[0].state'");
  assert.deepEqual(r.params, [{ name: "sha", shape: "sha", default: "$(git rev-parse HEAD)", seen: ["4e1c9a2"] }]);
  assert.deepEqual(find(["git reset --hard 9f8e7d6c"]).cmds, ["git reset --hard {sha}"]);
  // Two commits can't both be HEAD: neither gets a default.
  assert.deepEqual(find(["git cherry-pick a1b2c3d e5f6a7b"]).params, [
    { name: "sha", shape: "sha", seen: ["a1b2c3d"] }, { name: "sha_2", shape: "sha", seen: ["e5f6a7b"] },
  ]);
  // Not a sha: all letters, all digits, or outside the places a commit goes.
  for (const cmd of ["git checkout deadbeef", "git show 1234567", "echo abc1234def"]) assert.deepEqual(find([cmd]).cmds, [cmd], cmd);
});

test("pr: gh pr verbs and pull links, no default", () => {
  const r = find(["gh pr checks 12", "gh pr merge #12 --squash", "open https://github.com/acme/shop/pull/12"]);
  assert.deepEqual(r.cmds, ["gh pr checks {pr}", "gh pr merge #{pr} --squash", "open https://github.com/acme/shop/pull/{pr}"]);
  assert.deepEqual(r.params, [{ name: "pr", shape: "pr", seen: ["12"] }]);
  assert.equal(find(["gh api repos/acme/shop/pulls/7/comments"]).cmds[0], "gh api repos/acme/shop/pulls/{pr}/comments");
  // A bare number elsewhere is not the PR.
  assert.equal(find(["gh pr view 12", "gh run list --limit 12"]).cmds[1], "gh run list --limit 12");
});

test("port: host:port, --port, PORT=, and the dev-server forms; default the seen value", () => {
  const r = find(["PORT=3000 npm run dev", "curl -sf localhost:3000/health", "npx next start -p 3000", "lsof -ti:3000"]);
  assert.deepEqual(r.cmds, ["PORT={port} npm run dev", "curl -sf localhost:{port}/health", "npx next start -p {port}", "lsof -ti:{port}"]);
  assert.deepEqual(r.params, [{ name: "port", shape: "port", default: "3000", seen: ["3000"] }]);
  assert.deepEqual(find(["pnpm dev --port 5173 --strictPort"]).cmds, ["pnpm dev --port {port} --strictPort"]);
  assert.deepEqual(find(["python3 -m http.server 8000"]).cmds, ["python3 -m http.server {port}"]);
});

test("branch: refs/heads, checkout -b, push -u; stable branches stay literal", () => {
  const r = find(["git checkout -b fix/retry-loop", "git push -u origin fix/retry-loop", "gh pr create --head fix/retry-loop --fill"]);
  assert.deepEqual(r.cmds, ["git checkout -b {branch}", "git push -u origin {branch}", "gh pr create --head {branch} --fill"]);
  assert.deepEqual(r.params, [{ name: "branch", shape: "branch", default: "fix/retry-loop", seen: ["fix/retry-loop"] }]);
  assert.deepEqual(find(["git push origin 4e1c9a2:refs/heads/feat-x"]).cmds, ["git push origin {sha}:refs/heads/{branch}"]);
  for (const b of ["main", "master", "beta", "prod", "production", "dev", "develop", "staging", "trunk"]) assert.ok(STABLE_BRANCHES.has(b), b);
  assert.deepEqual(find(["git push -u origin main", "git push origin HEAD:refs/heads/beta"]).cmds, ["git push -u origin main", "git push origin HEAD:refs/heads/beta"]);
});

test("date: default today", () => {
  const r = find(["node scripts/report.mjs --since 2026-10-01"]);
  assert.deepEqual(r.cmds, ["node scripts/report.mjs --since {date}"]);
  assert.deepEqual(r.params, [{ name: "date", shape: "date", default: "$(date +%F)", seen: ["2026-10-01"] }]);
});

test("varied: a path segment after internal/ is {pkg}, default this run's value", () => {
  const step = (pkg: string) => `(cd backend && DOCKER_HOST=unix://$HOME/.colima/default/docker.sock TESTCONTAINERS_RYUK_DISABLED=true go test -tags integration ./internal/${pkg}/...)`;
  const r = find([step("workflow")], {}, { prior: [step("quickbooks")] });
  assert.deepEqual(r.cmds, [step("{pkg}")]);
  assert.deepEqual(r.params, [{ name: "pkg", shape: "varied", default: "workflow", seen: ["workflow", "quickbooks"] }]);
  // No prior run: nothing varies.
  assert.deepEqual(find([step("workflow")]).cmds, [step("workflow")]);
});

test("varied: the flag before it names it; otherwise arg1, arg2; aligned by program and order", () => {
  const r = find(["npm run build", "node build.mjs --target web", "node scripts/seed.mjs alpha"], {}, {
    prior: ["npm ci", "npm run build", "node build.mjs --target cli", "node scripts/seed.mjs beta"],
  });
  assert.deepEqual(r.cmds, ["npm run build", "node build.mjs --target {target}", "node scripts/seed.mjs {arg1}"]);
  assert.deepEqual(r.params.map((p) => [p.name, p.default, p.seen]), [["target", "web", ["web", "cli"]], ["arg1", "alpha", ["alpha", "beta"]]]);
  // --flag=value keeps the flag in the text.
  assert.deepEqual(find(["node build.mjs --target=web"], {}, { prior: ["node build.mjs --target=cli"] }).cmds, ["node build.mjs --target={target}"]);
});

test("varied: three differing tokens, a different length, or a shape already found: nothing", () => {
  assert.deepEqual(find(["node x.mjs a b c"], {}, { prior: ["node x.mjs d e f"] }).cmds, ["node x.mjs a b c"]);
  assert.deepEqual(find(["node x.mjs a"], {}, { prior: ["node x.mjs a b"] }).cmds, ["node x.mjs a"]);
  const r = find(["npm publish acme-cli-1.4.2.tgz"], {}, { prior: ["npm publish acme-cli-1.4.1.tgz"] });
  assert.deepEqual(r.cmds, ["npm publish acme-cli-{version}.tgz"]);
  assert.deepEqual(r.params.map((p) => p.name), ["version"]);
});

test("fillParams fills what it knows and leaves the rest", () => {
  assert.equal(fillParams("git push origin {sha}:refs/heads/{branch} # {other}", { sha: "4e1c9a2", branch: "fix/x" }), "git push origin 4e1c9a2:refs/heads/fix/x # {other}");
  assert.equal(fillParams("jq '{name: .a}'", { name: "x" }), "jq '{name: .a}'");
});

test("resolveParams: from the ask, then the default, then last seen, with notes", () => {
  const defs = [
    { name: "version", shape: "version" as const, seen: ["0.22.1"] },
    { name: "sha", shape: "sha" as const, default: "$(git rev-parse HEAD)", seen: ["4e1c9a2"] },
    { name: "pkg", shape: "varied" as const, default: "workflow", seen: ["workflow", "quickbooks"] },
    { name: "pr", shape: "pr" as const, seen: [] },
  ];
  assert.deepEqual(resolveParams(defs, { version: "1.4.2" }), {
    values: { version: "1.4.2", sha: "$(git rev-parse HEAD)", pkg: "workflow" },
    notes: ["{version} is 1.4.2, from the ask.", "{pkg} is workflow, as last time; change it if the ask names another."],
  });
  assert.deepEqual(resolveParams(defs, { sha: "9f8e7d6", pr: "12" }), {
    values: { version: "0.22.1", sha: "9f8e7d6", pkg: "workflow", pr: "12" },
    notes: ["{version} is 0.22.1, as last time; change it if the ask names another.", "{sha} is 9f8e7d6, from the ask.", "{pkg} is workflow, as last time; change it if the ask names another.", "{pr} is 12, from the ask."],
  });
});

test("params in metadata and back", () => {
  const defs = [
    { name: "version", shape: "version" as const, seen: ["0.22.1"] },
    { name: "sha", shape: "sha" as const, default: "$(git rev-parse HEAD)", seen: ["4e1c9a2"] },
    { name: "pkg", shape: "varied" as const, default: "workflow", seen: ["workflow"] },
    { name: "version_2", shape: "version" as const, seen: ["1.0.0"] },
    { name: "date", shape: "date" as const, default: "$(date +%F)", seen: [] },
  ];
  const meta = paramsToMeta(defs);
  assert.equal(meta, "version, sha=$(git rev-parse HEAD), pkg=workflow, version_2, date=$(date +%F)");
  assert.deepEqual(metaToParams(meta), [
    { name: "version", shape: "version", seen: [] },
    { name: "sha", shape: "sha", default: "$(git rev-parse HEAD)", seen: [] },
    { name: "pkg", shape: "varied", default: "workflow", seen: [] },
    { name: "version_2", shape: "version", seen: [] },
    { name: "date", shape: "date", default: "$(date +%F)", seen: [] },
  ]);
  assert.deepEqual(metaToParams(undefined), []);
  assert.deepEqual(metaToParams("  "), []);
  // A hand-edited name that isn't a parameter name is dropped.
  assert.deepEqual(metaToParams("ok, bad name=1, 9x").map((p) => p.name), ["ok"]);
});

test("g2 review: a commit, PR or version the run named once more is the same param wherever it stands", () => {
  const sha = "4e1c9a2b8f6e0d1c2b3a4f5e6d7c8b9a0f1e2d3c";
  for (const [cmd, want] of [
    ["git merge 4e1c9a2b", "git merge {sha}"], ["git rebase --onto main 4e1c9a2b", "git rebase --onto main {sha}"],
    ["git worktree add ../hotfix 4e1c9a2b", "git worktree add ../hotfix {sha}"], [`git branch hotfix ${sha}`, "git branch hotfix {sha}"],
    ["git -C backend cherry-pick 4e1c9a2b", "git -C backend cherry-pick {sha}"], [`curl -s https://ci.example.test/build?commit=${sha}`, "curl -s https://ci.example.test/build?commit={sha}"],
  ] as const) assert.equal(find([cmd]).cmds[0], want, cmd);
  for (const verb of ["checkout", "reopen", "comment", "review", "update-branch", "ready"]) assert.equal(find([`gh pr ${verb} 1234`]).cmds[0], `gh pr ${verb} {pr}`, verb);
  // The version a run published, installed again to try it, is the same {version}; a pin of another version stays.
  assert.deepEqual(find(["npm publish trailhq-trail-code-0.22.1.tgz", "npm install -g @trailhq/[email protected]"]).cmds,
    ["npm publish trailhq-trail-code-{version}.tgz", "npm install -g @trailhq/trail-code@{version}"]);
  assert.deepEqual(find(["npm i [email protected] && npm publish acme-cli-2.0.1.tgz"]).cmds, ["npm i [email protected] && npm publish acme-cli-{version}.tgz"]);
});

test("g2 review: a varied word keeps the shell around it out of the param; a different flag is not a param", () => {
  const step = (f: string) => `(cd backend && gofmt -l internal/${f})`;
  const r = find([step("platformmcp/brain.go")], {}, { prior: [step("workflow/run.go")] });
  assert.deepEqual(r.cmds, ["(cd backend && gofmt -l internal/{pkg}.go)"]);
  assert.deepEqual(r.params.map((p) => [p.name, p.default]), [["pkg", "platformmcp/brain"]]);
  assert.deepEqual(find(["gofmt -l internal/x.go"], {}, { prior: ["gofmt -w internal/x.go"] }).cmds, ["gofmt -l internal/x.go"]);
});