@jagreehal/shepherd 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/doctor.ts CHANGED
@@ -6,7 +6,7 @@ import { parse } from "yaml";
6
6
  import { z } from "zod";
7
7
  import { defaultBranchReader, defaultBranchRef, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, type Config } from "./config.ts";
8
8
  import { bundledSkills } from "./install.ts";
9
- import { lensProblems } from "./lens.ts";
9
+ import { lensProblems, pluginRoots, skillDirs } from "./lens.ts";
10
10
 
11
11
  export type Check = { check: string; status: "ok" | "warn" | "fail"; detail: string; fix?: string };
12
12
 
@@ -20,15 +20,8 @@ const attempt = <T>(f: () => T): T | Error => {
20
20
  }
21
21
  };
22
22
 
23
- // Where a harness looks for skills: Claude Code, the shared .agents layout, Codex, OpenCode.
24
- const SKILL_DIRS = (home: string, repo: string) => [
25
- path.join(home, ".claude/skills"),
26
- path.join(repo, ".claude/skills"),
27
- path.join(home, ".agents/skills"),
28
- path.join(repo, ".agents/skills"),
29
- path.join(home, ".codex/skills"),
30
- path.join(home, ".config/opencode/skills"),
31
- ];
23
+ // Where a harness looks for skills: the bare-name directories, plus OpenCode's.
24
+ const SKILL_DIRS = (home: string, repo: string) => [...skillDirs(home, repo), path.join(home, ".config/opencode/skills")];
32
25
 
33
26
  /**
34
27
  * True when a workflow runs stamp on pull requests: a step that uses stamp's action, runs its package, or
@@ -80,10 +73,20 @@ export function doctor(bundleRoot: string, home: string, repo: string, personal:
80
73
  if (read instanceof Error) add("default branch", "fail", read.message, "git fetch origin <default branch>: policy and lenses are read from it");
81
74
  else add("default branch", "ok", "fetched");
82
75
 
83
- const missing = bundledSkills(path.join(bundleRoot, "skills")).filter((s) => !SKILL_DIRS(home, repo).some((d) => existsSync(path.join(d, s, "SKILL.md"))));
76
+ const bundled = bundledSkills(path.join(bundleRoot, "skills"));
77
+ const plugins = pluginRoots(home);
78
+ const asPlugin = plugins.get("shepherd");
79
+ const dirs = [...SKILL_DIRS(home, repo), ...(asPlugin ? [path.join(asPlugin, "skills")] : [])];
80
+ const missing = bundled.filter((s) => !dirs.some((d) => existsSync(path.join(d, s, "SKILL.md"))));
84
81
 
85
- if (missing.length) add("skills", "fail", `not installed: ${missing.join(", ")}`, "bunx @jagreehal/shepherd install (or --project, or --target <your agent's skills dir>)");
86
- else add("skills", "ok", "every bundled skill is installed");
82
+ if (missing.length) add("skills", "fail", `not installed: ${missing.join(", ")}`, "bunx @jagreehal/shepherd install (or --project, or --target <your agent's skills dir>), or install the shepherd plugin");
83
+ else add("skills", "ok", `every bundled skill is installed${asPlugin ? " (as a plugin)" : ""}`);
84
+
85
+ // Another plugin's skill under one of shepherd's names (pstack ships a `swarm`): Cursor does not namespace
86
+ // plugin skills, so `/swarm` there may load either. Shepherd's own loop loads its sub-skills by path.
87
+ const shared = [...plugins].filter(([name]) => name !== "shepherd").flatMap(([name, root]) => bundled.filter((s) => existsSync(path.join(root, "skills", s, "SKILL.md"))).map((s) => `${name}:${s}`));
88
+
89
+ if (shared.length) add("skill names", "warn", `other plugins ship skills under shepherd's names: ${shared.join(", ")}. /shepherd is unaffected; typed on its own, the name may load either`, "in Claude Code type the plugin prefix (/pstack:swarm); in Cursor, pick the skill from the / menu by its description");
87
90
 
88
91
  if (read instanceof Error) return checks;
89
92
 
package/src/install.ts CHANGED
@@ -3,12 +3,64 @@
3
3
  // may be the user's own skill that happens to share a name.
4
4
  import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
5
5
  import path from "node:path";
6
+ import { parse } from "yaml";
7
+ import { z } from "zod";
6
8
 
7
9
  export const MARKER = ".shepherd-installed";
8
10
 
9
11
  /** A workflow template with every `SHEPHERD_VERSION:` pin set to `version`, so each job runs the CLI that wrote it. */
10
12
  export const pinWorkflow = (text: string, version: string) => text.replaceAll(/SHEPHERD_VERSION: \S+/g, `SHEPHERD_VERSION: ${version}`);
11
13
 
14
+ /** Run the model job in a GitHub environment, so model keys stored as its secrets reach that job and no other. */
15
+ export function environmentWorkflow(text: string, name: string): string {
16
+ // The name lands in YAML: refuse anything that could end the scalar or start a new key.
17
+ if (!/^[\w.-]+$/.test(name)) throw new Error(`--environment "${name}": use letters, digits, ".", "_" and "-"`);
18
+
19
+ return text.replaceAll(/^( +)# environment: <name>.*$/gm, `$1environment: ${name} # the model keys are this environment's secrets: no other job reads them`);
20
+ }
21
+
22
+ /**
23
+ * A workflow rewritten from its current template, keeping what the installer or the team chose in the old copy: the
24
+ * model job's environment and the `workflows:` list naming their CI. Everything else is the template's.
25
+ */
26
+ export function upgradeWorkflow(template: string, existing: string, version: string, environment?: string) {
27
+ const kept: string[] = [];
28
+
29
+ // Read as YAML, not by pattern: a quoted environment or a multiline workflows list is just as valid, and losing
30
+ // either takes the model's keys away or stops reviews. Anything this cannot carry over refuses the upgrade.
31
+ const old = z
32
+ .object({
33
+ on: z.object({ workflow_run: z.object({ workflows: z.array(z.string()).min(1) }).optional() }).optional(),
34
+ jobs: z.record(z.string(), z.object({ environment: z.union([z.string(), z.object({ name: z.string() }).transform((e) => e.name)]).optional() })),
35
+ })
36
+ .safeParse(parse(existing));
37
+
38
+ if (!old.success) throw new Error(`cannot read its environment and workflows list (${old.error.issues[0]?.path.join(".")}): update it by hand`);
39
+
40
+ const envs = [...new Set(Object.values(old.data.jobs).flatMap((j) => (j.environment === undefined ? [] : [j.environment])))];
41
+
42
+ if (!environment && envs.length > 1) throw new Error(`its jobs use different environments (${envs.join(", ")}): update it by hand`);
43
+
44
+ const env = environment ?? envs[0];
45
+ let text = pinWorkflow(template, version);
46
+
47
+ if (env) {
48
+ text = environmentWorkflow(text, env);
49
+ kept.push(`environment ${env}`);
50
+ }
51
+
52
+ const workflows = old.data.on?.workflow_run?.workflows;
53
+
54
+ if (workflows && /^ +workflows: \[.*\]\s*$/m.test(text)) {
55
+ const list = `[${workflows.map((w) => (/^[\w.-]+$/.test(w) ? w : JSON.stringify(w))).join(", ")}]`;
56
+
57
+ text = text.replace(/^( +workflows: )\[.*\]\s*$/m, `$1${list}`);
58
+ kept.push(`workflows ${list}`);
59
+ }
60
+
61
+ return { text, kept };
62
+ }
63
+
12
64
  // Command files are single files, so they carry the marker as a comment line instead.
13
65
  const COMMAND_MARKER = "<!-- shepherd-installed -->";
14
66
 
package/src/lens.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  // Custom lenses: any skill, wrapped by swarm as a review-only reviewer whose `## Fix` section steers
2
2
  // triage. This file reads and writes the lens files and finds skills on disk; swarm itself reads the
3
3
  // repository's file from the default branch at review time (skills/swarm/references/custom-lenses.md).
4
- import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
4
+ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
5
5
  import path from "node:path";
6
6
  import { parse, stringify } from "yaml";
7
7
  import { z } from "zod";
@@ -49,6 +49,26 @@ export function opencodeAgents(choice: { ladder: string[] | null; models: Record
49
49
  };
50
50
  }
51
51
 
52
+ // OpenCode's own agents, which pick a model of their own when nothing names one (on Bedrock, a `global.` profile that
53
+ // can leave the region).
54
+ const OPENCODE_BUILT_INS = ["build", "plan", "general", "explore", "title", "summary", "compaction"];
55
+
56
+ /**
57
+ * OpenCode's config for a CI run: shepherd's agents, every built-in agent and the small model on the session model, and
58
+ * only the providers the plan names enabled. PR content never reaches a provider or model the team did not choose.
59
+ */
60
+ export function ciOpencodeConfig(session: string, choice: { ladder: string[] | null; models: Record<string, string> }) {
61
+ const { agent } = opencodeAgents(choice);
62
+ const models = [session, ...Object.values(agent).map((a) => a.model)];
63
+
64
+ return {
65
+ model: session,
66
+ small_model: session,
67
+ enabled_providers: [...new Set(models.map((m) => m.split("/")[0]!))].sort(),
68
+ agent: { ...Object.fromEntries(OPENCODE_BUILT_INS.map((name) => [name, { model: session }])), ...agent },
69
+ };
70
+ }
71
+
52
72
  // stamp's `provider:model` names where OpenCode's provider id differs; every other provider keeps its name.
53
73
  const OPENCODE_PROVIDER = new Map([["bedrock", "amazon-bedrock"], ["vertex", "google-vertex"]]);
54
74
 
@@ -71,6 +91,13 @@ export function pinModel(file: string, name: string, model: string): void {
71
91
  write(file, { ...current, models: { ...current.models, [name]: ModelId.parse(model) } });
72
92
  }
73
93
 
94
+ /** Set CI settings under `ci:`, keeping everything else in the file. ConfigSchema checks them as it reads them back. */
95
+ export function setCi(file: string, values: Record<string, string>): void {
96
+ const current = readFile(file);
97
+
98
+ write(file, ConfigSchema.parse({ ...current, ci: { ...current.ci, ...values } }));
99
+ }
100
+
74
101
  /** Name a model: `tier` becomes usable in the ladder and in pins, and swapping its model swaps it everywhere. */
75
102
  export function setTier(file: string, tier: string, model: string): void {
76
103
  if (!LENS_NAME.test(tier)) throw new Error(`"${tier}" must be lowercase letters, digits, and dashes`);
@@ -95,6 +122,8 @@ const PROVIDER_KEY_ENV = new Map([
95
122
  ["amazon-bedrock", "AWS_BEARER_TOKEN_BEDROCK"],
96
123
  ]);
97
124
 
125
+ export const PROVIDER_KEY_ENVS = [...PROVIDER_KEY_ENV.values()];
126
+
98
127
  /** The key variable for an OpenCode model id's provider, or null when shepherd does not know it. */
99
128
  export const providerKeyEnv = (opencodeId: string): string | null => PROVIDER_KEY_ENV.get(opencodeId.split("/")[0]!) ?? null;
100
129
 
@@ -104,8 +133,11 @@ export function setLadder(file: string, ladder: string[]): void {
104
133
  }
105
134
 
106
135
  function write(file: string, contents: LensFile): void {
136
+ // The file's leading comments, the editor's $schema line among them, survive every edit.
137
+ const head = existsSync(file) ? (/^(?:#.*\n)*/.exec(readFileSync(file, "utf8"))?.[0] ?? "") : "";
138
+
107
139
  mkdirSync(path.dirname(file), { recursive: true });
108
- writeFileSync(file, stringify(contents));
140
+ writeFileSync(file, head + stringify(contents));
109
141
  }
110
142
 
111
143
  /** Add or replace one lens, keeping every other entry in the file. */
@@ -288,16 +320,68 @@ export function detectStacks(files: string[], read: (rel: string) => string | nu
288
320
  return lensTemplates().filter((t) => found.has(t));
289
321
  }
290
322
 
291
- /** The directory holding the skill's SKILL.md: a path against the repository, or a name in the usual skills directories. */
323
+ // Claude Code's record of installed plugins, keyed `<plugin>@<marketplace>`.
324
+ const InstallRecord = z.object({ plugins: z.record(z.string(), z.array(z.object({ installPath: z.string() }))) });
325
+
326
+ // A skill an installed plugin ships, as Claude Code names it: `<plugin>:<skill>`, e.g. `pstack:principle-fix-root-causes`.
327
+ const PLUGIN_SKILL = /^([\w.-]+):([\w.-]+)$/;
328
+
329
+ const subdirs = (dir: string) => (existsSync(dir) ? readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => path.join(dir, d.name)) : []);
330
+
331
+ /** The newest of a plugin's cached versions: harnesses keep old ones beside it until they prune. */
332
+ const newest = (dirs: string[]) => dirs.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
333
+
334
+ /**
335
+ * Each installed plugin's root, by plugin name: Claude Code's from its install record, Cursor's from its
336
+ * plugin cache (`<marketplace>/<plugin>/<version>`) and local plugins. A plugin keeps its skills in `skills/`.
337
+ */
338
+ export function pluginRoots(home: string): Map<string, string> {
339
+ const roots = new Map<string, string>();
340
+ const file = path.join(home, ".claude", "plugins", "installed_plugins.json");
341
+ const record = InstallRecord.safeParse(existsSync(file) ? parseJson(readFileSync(file, "utf8")) : null);
342
+
343
+ for (const [key, installs] of Object.entries(record.success ? record.data.plugins : {})) {
344
+ const root = installs.at(-1)?.installPath;
345
+
346
+ if (root) roots.set(key.split("@")[0]!, root);
347
+ }
348
+
349
+ const cursor = path.join(home, ".cursor", "plugins");
350
+
351
+ for (const plugin of subdirs(path.join(cursor, "cache")).flatMap(subdirs)) {
352
+ const root = newest(subdirs(plugin));
353
+
354
+ if (root && !roots.has(path.basename(plugin))) roots.set(path.basename(plugin), root);
355
+ }
356
+
357
+ for (const root of subdirs(path.join(cursor, "local"))) if (!roots.has(path.basename(root))) roots.set(path.basename(root), root);
358
+
359
+ return roots;
360
+ }
361
+
362
+ /** Where a harness looks for skills by bare name: Claude Code, the shared .agents layout, Codex, Cursor. */
363
+ export const skillDirs = (home: string, repoRoot: string) =>
364
+ [".claude/skills", ".agents/skills", ".codex/skills", ".cursor/skills"].map((d) => path.join(home, d)).concat([".claude/skills", ".agents/skills", ".cursor/skills"].map((d) => path.join(repoRoot, d)));
365
+
366
+ /**
367
+ * The directory holding the skill's SKILL.md: a pinned pack lens, a path against the repository, an
368
+ * installed plugin's skill (`<plugin>:<skill>`), or a name in the usual skills directories.
369
+ */
292
370
  export function resolveSkill(ref: string, home: string, repoRoot: string): string | null {
293
371
  const pinned = lensCache(home, ref);
294
372
 
295
373
  if (pinned) return existsSync(path.join(pinned, "SKILL.md")) ? pinned : null;
296
- const expanded = ref.startsWith("~/") ? path.join(home, ref.slice(2)) : ref;
374
+ const plugin = PLUGIN_SKILL.exec(ref);
297
375
 
298
- const candidates = expanded.includes("/")
299
- ? [path.resolve(repoRoot, expanded)]
300
- : [".claude/skills", ".agents/skills", ".codex/skills"].map((d) => path.join(home, d, expanded)).concat([".claude/skills", ".agents/skills"].map((d) => path.join(repoRoot, d, expanded)));
376
+ if (plugin) {
377
+ const root = pluginRoots(home).get(plugin[1]!);
378
+ const dir = root && path.join(root, "skills", plugin[2]!);
379
+
380
+ return dir && existsSync(path.join(dir, "SKILL.md")) ? dir : null;
381
+ }
382
+
383
+ const expanded = ref.startsWith("~/") ? path.join(home, ref.slice(2)) : ref;
384
+ const candidates = expanded.includes("/") ? [path.resolve(repoRoot, expanded)] : skillDirs(home, repoRoot).map((d) => path.join(d, expanded));
301
385
 
302
386
  return candidates.find((dir) => existsSync(path.join(dir, "SKILL.md"))) ?? null;
303
387
  }
@@ -10,9 +10,10 @@
10
10
  # report then becomes a public artifact.
11
11
  #
12
12
  # Secrets: SHEPHERD_API_KEY (or the provider's own key) for the model.
13
- # Variables: SHEPHERD_MODEL (a model or tier; empty = the team's models.loop or top rung), AWS_REGION (Bedrock),
14
- # AUDIT_PLAYS (space-separated play names; empty = the default below),
15
- # AUDIT_PUBLIC (`true` to run on a public repository, publishing the report).
13
+ # Variables: SHEPHERD_MODEL (optional override of the team's models.loop in .shepherd/config.yml, else its top rung), AWS_REGION (Bedrock),
14
+ # AUDIT_PLAYS (ci.audit.plays; space-separated play names; empty = the default),
15
+ # AUDIT_PUBLIC (ci.audit.public: `true` to run on a public repository, publishing the report).
16
+ # Each variable overrides its key in .shepherd/config.yml.
16
17
  name: shepherd-audit
17
18
  on:
18
19
  schedule:
@@ -20,7 +21,7 @@ on:
20
21
  workflow_dispatch:
21
22
  inputs:
22
23
  plays:
23
- description: Plays to run, space-separated (empty = AUDIT_PLAYS or the default)
24
+ description: Plays to run, space-separated (empty = ci.audit.plays, AUDIT_PLAYS, or the default)
24
25
  required: false
25
26
 
26
27
  permissions: {}
@@ -34,7 +35,30 @@ jobs:
34
35
  outputs:
35
36
  private: ${{ steps.repo.outputs.private }}
36
37
  default_branch: ${{ steps.repo.outputs.default_branch }}
38
+ audit_public: ${{ steps.settings.outputs.audit_public }}
39
+ audit_plays: ${{ steps.settings.outputs.audit_plays }}
40
+ aws_region: ${{ steps.settings.outputs.aws_region }}
41
+ env:
42
+ SHEPHERD_VERSION: 0.3.0 # pinned, as in audit
37
43
  steps:
44
+ # Settings from the default branch's .shepherd/config.yml (ci:), each overridden by its variable when set.
45
+ - uses: actions/checkout@v4
46
+ with:
47
+ ref: ${{ github.event.repository.default_branch || github.ref_name }}
48
+ sparse-checkout: .shepherd
49
+ persist-credentials: false
50
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
51
+ - name: Settings
52
+ id: settings
53
+ env:
54
+ SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
55
+ GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
56
+ AWS_REGION: ${{ vars.AWS_REGION }}
57
+ AUDIT_PLAYS: ${{ vars.AUDIT_PLAYS }}
58
+ AUDIT_PUBLIC: ${{ vars.AUDIT_PUBLIC }}
59
+ run: |
60
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
61
+ "$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
38
62
  - id: repo
39
63
  shell: bash
40
64
  env:
@@ -43,8 +67,9 @@ jobs:
43
67
 
44
68
  audit:
45
69
  needs: repo
46
- if: needs.repo.outputs.private == 'true' || vars.AUDIT_PUBLIC == 'true'
70
+ if: needs.repo.outputs.private == 'true' || needs.repo.outputs.audit_public == 'true'
47
71
  runs-on: ubuntu-latest
72
+ # environment: <name> `shepherd workflows --environment <name>`: store the model keys as that environment's secrets, readable by this job only
48
73
  timeout-minutes: 60
49
74
  concurrency:
50
75
  group: shepherd-audit
@@ -54,7 +79,7 @@ jobs:
54
79
  env:
55
80
  SHEPHERD_VERSION: 0.3.0 # pinned: this runs with the repo's secrets, so bumps are deliberate
56
81
  PLAYBOOK_SHA: 65d4efd2cd0b081d52101e9708792b944e4ddebb # OWASP/secure-agent-playbook, pinned: the plays are instructions
57
- PLAYS: ${{ github.event.inputs.plays || vars.AUDIT_PLAYS || 'secrets-scan sca-audit iac-security-review code-review-security' }}
82
+ PLAYS: ${{ github.event.inputs.plays || needs.repo.outputs.audit_plays }}
58
83
  steps:
59
84
  - uses: actions/checkout@v4
60
85
  with:
@@ -98,7 +123,7 @@ jobs:
98
123
  GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
99
124
  XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
100
125
  AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
101
- AWS_REGION: ${{ vars.AWS_REGION }} # for a bedrock: model
126
+ AWS_REGION: ${{ needs.repo.outputs.aws_region }} # ci.aws_region or the AWS_REGION variable, for a bedrock: model
102
127
  SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
103
128
  SHEPHERD_DEFAULT_BRANCH: ${{ needs.repo.outputs.default_branch }}
104
129
  OPENCODE_DISABLE_PROJECT_CONFIG: "1" # the checkout's opencode.json, .opencode/ plugins and AGENTS.md stay out of the agent's config
@@ -112,8 +137,10 @@ jobs:
112
137
  key_env=$(jq -r '.key_env // empty' <<<"$plan")
113
138
  if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
114
139
  unset SHEPHERD_API_KEY
115
- # An unset secret arrives as "": a blank key would hide the provider's other credentials.
116
- for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do [ -n "${!k:-}" ] || unset "$k"; done
140
+ # Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
141
+ # provider's other credentials.
142
+ keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
143
+ for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do { [ -n "${!k:-}" ] && [[ "$keys" == *" $k "* ]]; } || unset "$k"; done
117
144
  OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
118
145
  opencode run --auto -m "$model" --title "shepherd audit" "Run a security audit of this repository (the current directory, its default branch).
119
146
  For each play name in: $PLAYS
@@ -125,6 +152,8 @@ jobs:
125
152
  then each finding with severity, CWE, file:line and the fix. Never write a secret's value: name its type, file and
126
153
  line, and the first 4 characters at most. Nobody is watching this session: never wait for an answer."
127
154
  test -s "$RUNNER_TEMP/audit/report.md" || { echo "::error::the audit wrote no report"; exit 1; }
155
+ # The team's branding, from the default branch, for the report job's header.
156
+ shepherd branding | jq -r .headers.audit > "$RUNNER_TEMP/audit/header.md" || rm -f "$RUNNER_TEMP/audit/header.md"
128
157
  - name: Withhold a report that carries a credential
129
158
  shell: bash
130
159
  run: |
@@ -147,7 +176,7 @@ jobs:
147
176
  - uses: actions/upload-artifact@v4
148
177
  with:
149
178
  name: shepherd-audit
150
- path: ${{ runner.temp }}/audit
179
+ path: ${{ runner.temp }}/audit/report.md # the checked file only, never scanner output beside it
151
180
  retention-days: 30
152
181
 
153
182
  report:
@@ -171,7 +200,11 @@ jobs:
171
200
  echo "Public repository (AUDIT_PUBLIC): the report is in the run's shepherd-audit artifact ($RUN_URL)." >> "$GITHUB_STEP_SUMMARY"
172
201
  exit 0
173
202
  fi
174
- body=$(printf '> 🤖 Automated comment by **Shepherd audit**, not written by a human\n\nRun: %s\n\n%s' "$RUN_URL" "$(head -c 60000 audit/report.md)")
203
+ # The header came out of a job a model ran in: one line with the automated prefix, or the default.
204
+ header='> 🤖 Automated comment by **Shepherd audit**, not written by a human'
205
+ custom=$(head -c 400 audit/header.md 2>/dev/null || true)
206
+ if [[ "$custom" == "> 🤖 Automated comment by "* && "$custom" != *$'\n'* ]]; then header=$custom; fi
207
+ body=$(printf '%s\n\nRun: %s\n\n%s' "$header" "$RUN_URL" "$(head -c 60000 audit/report.md)")
175
208
  gh label create shepherd-audit --repo "$REPO" --color B60205 --description "shepherd's scheduled security audit" 2>/dev/null || true
176
209
  issue=$(gh issue list --repo "$REPO" --label shepherd-audit --state open --json number --jq '.[0].number // empty')
177
210
  if [ -n "$issue" ]; then gh issue comment "$issue" --repo "$REPO" --body "$body"
@@ -17,8 +17,8 @@
17
17
  #
18
18
  # Secrets: SHEPHERD_TOKEN (contents, pull requests: write) for `open`, so the fix PR starts CI and stamp;
19
19
  # with github.token the PR opens but no workflow runs on it. SHEPHERD_API_KEY (or the provider's own key) for the model.
20
- # Variables: SHEPHERD_MODEL (a model or tier; empty = the team's models.loop or top rung), AWS_REGION (Bedrock),
21
- # INCIDENT_PATHS (extended regex; empty = ^src/).
20
+ # Variables: SHEPHERD_MODEL (optional override of the team's models.loop in .shepherd/config.yml, else its top rung), AWS_REGION (Bedrock),
21
+ # INCIDENT_PATHS (ci.incident_paths in .shepherd/config.yml; the variable overrides it; empty = ^src/).
22
22
  name: shepherd-incident
23
23
  on:
24
24
  workflow_run:
@@ -42,6 +42,7 @@ jobs:
42
42
  && github.event.workflow_run.head_branch == github.event.repository.default_branch)
43
43
  || github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
44
44
  runs-on: ubuntu-latest
45
+ # environment: <name> `shepherd workflows --environment <name>`: store the model keys as that environment's secrets, readable by this job only
45
46
  timeout-minutes: 45
46
47
  # On the job, not the workflow: every green CI run starts this workflow and skips, and a workflow-level group
47
48
  # would hand that skip the one pending slot a real incident needs. One at a time, so a repeat signal dedupes.
@@ -99,7 +100,7 @@ jobs:
99
100
  GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
100
101
  XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
101
102
  AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
102
- AWS_REGION: ${{ vars.AWS_REGION }} # for a bedrock: model
103
+ AWS_REGION: ${{ vars.AWS_REGION }} # overrides ci.aws_region, for a bedrock: model
103
104
  SHEPHERD_MODEL: ${{ vars.SHEPHERD_MODEL }} # a model or tier; empty = the team's models.loop, top rung, or the default
104
105
  SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
105
106
  OPENCODE_DISABLE_PROJECT_CONFIG: "1"
@@ -109,13 +110,16 @@ jobs:
109
110
  # The team's models, from the default branch: the session model, the variable its key goes in, and the
110
111
  # OpenCode agents that carry the ladder and pins, so each runner gets its own model.
111
112
  plan=$(shepherd ci-models)
113
+ AWS_REGION=$(shepherd ci-settings | jq -r .aws_region.value) && export AWS_REGION # ci.aws_region, or the variable
112
114
  model=$(jq -r .model <<<"$plan")
113
115
  echo "session model: $model ($(jq -r .source <<<"$plan"))"
114
116
  key_env=$(jq -r '.key_env // empty' <<<"$plan")
115
117
  if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
116
118
  unset SHEPHERD_API_KEY
117
- # An unset secret arrives as "": a blank key would hide the provider's other credentials.
118
- for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do [ -n "${!k:-}" ] || unset "$k"; done
119
+ # Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
120
+ # provider's other credentials.
121
+ keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
122
+ for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do { [ -n "${!k:-}" ] && [[ "$keys" == *" $k "* ]]; } || unset "$k"; done
119
123
  OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
120
124
  opencode run --auto -m "$model" --title "incident" "Load the incident skill and run it on the signal in $RUNNER_TEMP/signal.txt
121
125
  (a run URL, or an error or alert text).
@@ -137,11 +141,39 @@ jobs:
137
141
  path: ${{ runner.temp }}/handoff
138
142
  if-no-files-found: ignore
139
143
 
140
- open:
144
+ # The paths a fix may change, resolved in a job with no model and no secret: the model cannot choose them.
145
+ settings:
141
146
  needs: investigate
142
147
  runs-on: ubuntu-latest
148
+ permissions:
149
+ contents: read
150
+ outputs:
151
+ incident_paths: ${{ steps.settings.outputs.incident_paths }}
152
+ env:
153
+ SHEPHERD_VERSION: 0.3.0 # pinned, as in investigate
154
+ steps:
155
+ # Settings from the default branch's .shepherd/config.yml (ci:), each overridden by its variable when set.
156
+ - uses: actions/checkout@v4
157
+ with:
158
+ ref: ${{ github.event.repository.default_branch || github.ref_name }}
159
+ sparse-checkout: .shepherd
160
+ persist-credentials: false
161
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
162
+ - name: Settings
163
+ id: settings
164
+ env:
165
+ SHEPHERD_DEFAULT_BRANCH: ${{ github.event.repository.default_branch || github.ref_name }}
166
+ GH_TOKEN: ${{ github.token }} # gh api, for a github: pack the policy extends
167
+ INCIDENT_PATHS: ${{ vars.INCIDENT_PATHS }}
168
+ run: |
169
+ bun add -g "@jagreehal/shepherd@$SHEPHERD_VERSION"
170
+ "$HOME/.bun/bin/shepherd" ci-settings --outputs >> "$GITHUB_OUTPUT"
171
+
172
+ open:
173
+ needs: [investigate, settings]
174
+ runs-on: ubuntu-latest
143
175
  env:
144
- INCIDENT_PATHS: ${{ vars.INCIDENT_PATHS || '^src/' }} # extended regex every changed path must match
176
+ INCIDENT_PATHS: ${{ needs.settings.outputs.incident_paths }} # extended regex every changed path must match
145
177
  permissions:
146
178
  contents: write
147
179
  pull-requests: write
@@ -174,6 +206,7 @@ jobs:
174
206
  # its own so a failure stops here instead of passing an empty list; an empty change is refused too.
175
207
  git diff -z --no-renames --name-only "origin/$DEFAULT...$branch" > ../changed
176
208
  [ -s ../changed ] || { echo "::error::$branch changes nothing"; exit 1; }
209
+ [ -n "$INCIDENT_PATHS" ] || { echo "::error::no INCIDENT_PATHS: an empty pattern would allow every path"; exit 1; }
177
210
  outside=$(tr '\0' '\n' < ../changed | grep -Ev -- "$INCIDENT_PATHS" || [ $? -eq 1 ])
178
211
  [ -z "$outside" ] || { echo "::error::the fix changes paths outside $INCIDENT_PATHS; a person should look:"; echo "$outside"; exit 1; }
179
212
  git push origin "$branch:refs/heads/$branch"