@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/README.md +8 -1
- package/THIRD_PARTY_NOTICES.md +30 -0
- package/commands/shepherd.md +3 -2
- package/lenses/pstack/SKILL.md +33 -0
- package/package.json +5 -2
- package/packs/pstack.yml +8 -0
- package/schema/config.json +340 -0
- package/skills/ci-repair/SKILL.md +11 -3
- package/skills/incident/SKILL.md +4 -2
- package/skills/lens-import/SKILL.md +5 -3
- package/skills/shepherd/SKILL.md +43 -17
- package/skills/shepherd/references/dispatch.md +11 -6
- package/skills/shepherd/references/models.md +1 -1
- package/skills/swarm/SKILL.md +108 -72
- package/skills/swarm/references/custom-lenses.md +12 -4
- package/skills/swarm/references/formats.md +3 -3
- package/skills/triage/SKILL.md +16 -1
- package/src/cli.ts +189 -23
- package/src/config.ts +169 -2
- package/src/doctor.ts +16 -13
- package/src/install.ts +52 -0
- package/src/lens.ts +91 -7
- package/templates/shepherd-audit.yml +44 -11
- package/templates/shepherd-incident.yml +40 -7
- package/templates/shepherd.yml +148 -25
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:
|
|
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
|
|
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",
|
|
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
|
-
|
|
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
|
|
374
|
+
const plugin = PLUGIN_SKILL.exec(ref);
|
|
297
375
|
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
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 (
|
|
14
|
-
# AUDIT_PLAYS (space-separated play names; empty = the default
|
|
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' ||
|
|
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 ||
|
|
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: ${{
|
|
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
|
-
#
|
|
116
|
-
|
|
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
|
-
|
|
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 (
|
|
21
|
-
# INCIDENT_PATHS (
|
|
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
|
-
#
|
|
118
|
-
|
|
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
|
-
|
|
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: ${{
|
|
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"
|