@jagreehal/shepherd 0.6.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/cli.ts CHANGED
@@ -11,15 +11,19 @@
11
11
  // shepherd local finish <record.json> [--base <ref>] (check a local review against that change; complete writes a receipt)
12
12
  // shepherd local status [--base <ref>] (is the change on disk the one a complete review covered?)
13
13
  // shepherd local demo [<dir>] (a repository with planted bugs to try /shepherd --local on)
14
- // shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks] (scaffold .shepherd/config.yml)
14
+ // shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks] [--model <id>] (scaffold .shepherd/config.yml)
15
15
  // shepherd config validate (the working tree's policy: exits 1 on a problem)
16
+ // shepherd config schema (the JSON Schema of .shepherd/config.yml, for editors)
16
17
  // shepherd config explain [--json] [--working-tree] (effective policy and where each setting came from)
18
+ // shepherd branding [--working-tree] (JSON: the name, avatar, glyphs and headers posted comments use)
19
+ // shepherd ci-settings [--outputs] (the CI settings from variables, the default branch's ci:, defaults)
20
+ // shepherd fanout [--base <ref>] [--working-tree] (JSON: the lenses swarm starts beside the router, each with its scope)
17
21
  // shepherd preview [--recipe <name>] [--base <ref>] [--working-tree] (what would run on your change)
18
22
  // shepherd doctor [--json] (is this machine and repository set up? each problem says what to do)
19
23
  // shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>... (run it; check it kept to the mode)
20
24
  // shepherd trace event <stage> <start|end> --pr <n> [--round <n>] [--outcome ok|failed|skipped] [--retries <n>] [--head <sha>]
21
25
  // shepherd stack <pr> (JSON: a stacked parent and the range to review, or a wrong base)
22
- // shepherd workflows [--audit] (copy the shepherd and incident workflows, and the audit one, into .github/workflows)
26
+ // shepherd workflows [--audit] [--upgrade] [--model <id>] [--environment <name>] [--label <name>] [--aws-region <region>] (copy the shepherd and incident workflows, and the audit one, into .github/workflows)
23
27
  // shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>
24
28
  // shepherd trace flush --pr <n> --repo <owner/repo> --head <sha> --outcome <how it ended> [--base <sha>] [--ci-run <id> --ci-attempt <n>] [--related <traceparent>]...
25
29
  //
@@ -36,20 +40,23 @@ import path from "node:path";
36
40
  import { parseArgs } from "node:util";
37
41
  import { parse as parseYaml, stringify } from "yaml";
38
42
  import { z } from "zod";
39
- import { CI_DEFAULT_MODEL, ciModel, type Config, ConfigSchema, defaultBranchReader, type Effective, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, policyProblems, PRESETS, preview, type Read, TEAM_FILES } from "./config.ts";
43
+ import { branding, CI_DEFAULT_MODEL, ciModel, ciSettings, type Config, ConfigSchema, defaultBranchDir, defaultBranchReader, type Effective, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, policyProblems, PRESETS, preview, type Read, TEAM_FILES, configJsonSchema, schemaLine } from "./config.ts";
40
44
  import { ghThreads, snapshot, verdict } from "./acceptance.ts";
41
45
  import { doctor } from "./doctor.ts";
42
46
  import { fileLedger, notify, notifyOn, STATES, statusLedger } from "./notify.ts";
43
47
  import { collect, collectEscapes, score } from "./garden.ts";
44
48
  import { collectTraces, tempoHeaders, traceLimits, traceScores } from "./garden-traces.ts";
45
- import { install, type Outcome, pinWorkflow, uninstall } from "./install.ts";
49
+ import { environmentWorkflow, install, type Outcome, pinWorkflow, uninstall, upgradeWorkflow } from "./install.ts";
46
50
  import { buildDemo, captureChange, demoBugs, finish, receiptStatus } from "./local.ts";
47
51
  import { prStack } from "./stack.ts";
48
52
  import { flush, recordEvent, traceFile } from "./trace.ts";
49
- import { addLens, BUILT_IN_LENSES, pluginRoots, lensTemplates, globalLensFile, lensProblems, newLens, opencodeAgents, opencodeModel, providerKeyEnv, setTier, detectStacks, stackLens, pinModel, repoLensFile, resolveSkill, setLadder, skillDescription, type Lens } from "./lens.ts";
53
+ import { addLens, BUILT_IN_LENSES, ciOpencodeConfig, PROVIDER_KEY_ENVS, pluginRoots, lensTemplates, globalLensFile, lensProblems, newLens, opencodeAgents, opencodeModel, providerKeyEnv, setTier, detectStacks, stackLens, pinModel, repoLensFile, resolveSkill, setCi, setLadder, skillDescription, skillDirs, type Lens } from "./lens.ts";
50
54
 
51
55
  const BUNDLE_ROOT = path.resolve(import.meta.dir, "..");
52
56
 
57
+ /** This CLI's version: workflows and the policy's schema line pin to it. */
58
+ const bundleVersion = () => z.object({ version: z.string() }).parse(JSON.parse(readFileSync(path.join(BUNDLE_ROOT, "package.json"), "utf8"))).version;
59
+
53
60
  const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [--force]
54
61
  shepherd uninstall [--project | --target <dir>]
55
62
  shepherd lens new <name> [--from <template>] [--applies <glob>]... [--description <text>]
@@ -63,9 +70,13 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
63
70
  shepherd local finish <record.json> [--base <ref>]
64
71
  shepherd local status [--base <ref>]
65
72
  shepherd local demo [<dir>]
66
- shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks]
73
+ shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks] [--model <id>]
67
74
  shepherd config validate
75
+ shepherd config schema
68
76
  shepherd config explain [--json] [--working-tree]
77
+ shepherd branding [--working-tree]
78
+ shepherd ci-settings [--outputs]
79
+ shepherd fanout [--base <ref>] [--working-tree]
69
80
  shepherd preview [--recipe <name>] [--base <ref>] [--working-tree]
70
81
  shepherd doctor [--json]
71
82
  shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>...
@@ -73,7 +84,7 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
73
84
  shepherd trace flush --pr <n> --repo <owner/repo> --head <sha> --outcome <how it ended> [--base <sha>] [--ci-run <id> --ci-attempt <n>] [--related <traceparent>]...
74
85
  shepherd stack <pr>
75
86
  shepherd model-id <provider:model | provider/model>
76
- shepherd workflows [--audit]
87
+ shepherd workflows [--audit] [--upgrade] [--model <id>] [--environment <name>] [--label <name>] [--aws-region <region>]
77
88
  shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>`;
78
89
 
79
90
  const { values: opts, positionals } = parseArgs({
@@ -87,7 +98,9 @@ const { values: opts, positionals } = parseArgs({
87
98
  applies: { type: "string", multiple: true },
88
99
  description: { type: "string" },
89
100
  global: { type: "boolean", default: false },
90
- model: { type: "string" },
101
+ model: { type: "string" }, // lens add: the lens's model; init, workflows: the session model, written to models.loop
102
+ environment: { type: "string" }, // workflows: the GitHub environment whose secrets hold the model keys
103
+ upgrade: { type: "boolean", default: false }, // workflows: rewrite existing workflows from the current templates
91
104
  since: { type: "string" },
92
105
  file: { type: "string" }, // opencode-agents: a lenses.yml to read instead of the default branch's
93
106
  "min-prs": { type: "string", default: "3" },
@@ -103,6 +116,9 @@ const { values: opts, positionals } = parseArgs({
103
116
  recipe: { type: "string" },
104
117
  preset: { type: "string" }, // init: how far fixes go
105
118
  audit: { type: "boolean", default: false }, // workflows: also the scheduled OWASP playbook audit
119
+ outputs: { type: "boolean", default: false }, // ci-settings: key=value lines for $GITHUB_OUTPUT
120
+ label: { type: "string" }, // workflows: ci.label, the handoff label
121
+ "aws-region": { type: "string" }, // workflows: ci.aws_region, for a bedrock: model
106
122
  stacks: { type: "boolean", default: false }, // init: add a lens for each stack the repository uses
107
123
  pr: { type: "string" }, // acceptance: the PR whose threads must stay as they were; trace: the PR
108
124
  round: { type: "string" }, // trace: the quality-loop round
@@ -149,6 +165,9 @@ const orExit = <T>(run: () => T): T => {
149
165
  }
150
166
  };
151
167
 
168
+ // Secrets config explain shows only as set or unset.
169
+ const SECRETS = ["SHEPHERD_TOKEN", "SHEPHERD_API_KEY", "SHEPHERD_NOTIFY_WEBHOOK", ...new Set(PROVIDER_KEY_ENVS)];
170
+
152
171
  const MERGE_NOTE = "shepherd reads .shepherd/ from the default branch: commit and merge it before it takes effect.";
153
172
 
154
173
  if (command === "install") {
@@ -330,7 +349,7 @@ if (command === "install") {
330
349
  const { model, source } = ciModel(p, process.env.SHEPHERD_MODEL || undefined);
331
350
  const session = opencodeModel(model);
332
351
 
333
- const opencode = opencodeAgents(choice(p));
352
+ const opencode = ciOpencodeConfig(session, choice(p));
334
353
  // Every key the plan's models read, so the workflow can drop the rest before the model runs.
335
354
  const keyEnvs = [...new Set([session, ...Object.values(opencode.agent).map((a) => a.model)].flatMap((m) => providerKeyEnv(m) ?? []))].sort();
336
355
 
@@ -349,19 +368,71 @@ if (command === "install") {
349
368
  for (const name of ["shepherd.yml", "shepherd-incident.yml", ...(opts.audit ? ["shepherd-audit.yml"] : [])]) {
350
369
  const to = path.join(dest, name);
351
370
 
371
+ // Pin the workflow to the version that wrote it, so its skills match this CLI.
372
+ const version = bundleVersion();
373
+
374
+ if (existsSync(to) && opts.upgrade) {
375
+ const upgraded = orExit(() => upgradeWorkflow(readFileSync(path.join(BUNDLE_ROOT, "templates", name), "utf8"), readFileSync(to, "utf8"), version, opts.environment));
376
+
377
+ writeFileSync(to, upgraded.text);
378
+ console.log(`upgraded .github/workflows/${name} to ${version}${upgraded.kept.length ? ` (kept ${upgraded.kept.join(", ")})` : ""}`);
379
+ continue;
380
+ }
381
+
352
382
  if (existsSync(to)) {
353
- console.log(`kept .github/workflows/${name} (exists)`);
383
+ const kept = readFileSync(to, "utf8");
384
+ const scoped = opts.environment ? orExit(() => environmentWorkflow(kept, opts.environment!)) : kept;
385
+
386
+ // --environment on a rerun still scopes the model job: fill the template's placeholder, or say what to change.
387
+ if (scoped !== kept) {
388
+ writeFileSync(to, scoped);
389
+ console.log(`scoped .github/workflows/${name} to the ${opts.environment} environment`);
390
+ } else if (opts.environment && !kept.includes(`environment: ${opts.environment}`)) {
391
+ console.log(`kept .github/workflows/${name} (exists): add \`environment: ${opts.environment}\` to its model job by hand`);
392
+ } else console.log(`kept .github/workflows/${name} (exists): run \`shepherd workflows --upgrade\` to update it`);
393
+
354
394
  continue;
355
395
  }
356
396
 
357
- // Pin the workflow to the version that wrote it, so its skills match this CLI.
358
- const version = z.object({ version: z.string() }).parse(JSON.parse(readFileSync(path.join(BUNDLE_ROOT, "package.json"), "utf8"))).version;
397
+ const text = pinWorkflow(readFileSync(path.join(BUNDLE_ROOT, "templates", name), "utf8"), version);
359
398
 
360
- writeFileSync(to, pinWorkflow(readFileSync(path.join(BUNDLE_ROOT, "templates", name), "utf8"), version));
399
+ writeFileSync(to, opts.environment ? orExit(() => environmentWorkflow(text, opts.environment!)) : text);
361
400
  console.log(`wrote .github/workflows/${name}`);
362
401
  }
363
402
 
364
- console.log("\nNext: name your CI workflow in each file's `workflows:` list, add the SHEPHERD_TOKEN and OPENCODE_API_KEY secrets, then merge.\nOptional: SHEPHERD_LABEL (handoff label), SHEPHERD_NOTIFY_WEBHOOK (Slack or any JSON endpoint).");
403
+ // Settings go in the team policy, reviewed and versioned, rather than in repository variables.
404
+ if (opts.model) {
405
+ orExit(() => pinModel(repoLensFile(repoRoot), "loop", opts.model!));
406
+ console.log(`pinned models.loop: ${opts.model} in ${path.relative(repoRoot, repoLensFile(repoRoot))}`);
407
+ }
408
+
409
+ const ci: Record<string, string> = {};
410
+
411
+ if (opts.label) ci.label = opts.label;
412
+
413
+ if (opts["aws-region"]) ci.aws_region = opts["aws-region"];
414
+
415
+ if (Object.keys(ci).length) {
416
+ orExit(() => setCi(repoLensFile(repoRoot), ci));
417
+ console.log(`set ${Object.entries(ci).map(([k, v]) => `ci.${k}: ${v}`).join(", ")} in ${path.relative(repoRoot, repoLensFile(repoRoot))}`);
418
+ }
419
+
420
+ const keys = opts.environment ? `as secrets of the ${opts.environment} environment (only the model job reads them)` : "as repository secrets (or rerun with --environment <name> so only the model job can read them)";
421
+ const model = opts.model ? "" : "Name the session model in .shepherd/config.yml: shepherd models pin loop <model> (or rerun with --model). The SHEPHERD_MODEL variable overrides it when set.\n";
422
+
423
+ // SHEPHERD_TOKEN only pushes fixes: ask for it only when the policy pushes.
424
+ const pushes = (() => {
425
+ try {
426
+ return loadPolicy(workingTree, ghFetch, null).fixes.value.mode === "push";
427
+ } catch {
428
+ return true; // a policy that does not load yet: name the token rather than leave it out
429
+ }
430
+ })();
431
+
432
+ const token = pushes ? "add SHEPHERD_TOKEN as a repository secret and " : "";
433
+ const later = pushes ? "" : "SHEPHERD_TOKEN is not needed until fixes.mode is push.\n";
434
+
435
+ console.log(`\nNext: name your CI workflow in each file's \`workflows:\` list, ${token}add the model key (SHEPHERD_API_KEY, or the provider's own) ${keys}, then merge.\n${later}${model}Other settings (label, aws_region, notify_on, push_deny...) go under ci: in .shepherd/config.yml; shepherd config explain lists them. Optional secret: SHEPHERD_NOTIFY_WEBHOOK (Slack or any JSON endpoint).`);
365
436
  } else if (command === "notify") {
366
437
  const pr = Number(opts.pr);
367
438
  const state = STATES.find((s) => s === opts.state);
@@ -375,7 +446,16 @@ if (command === "install") {
375
446
  const url = `${process.env.GITHUB_SERVER_URL || "https://github.com"}/${opts.repo}/pull/${pr}`;
376
447
  const event = { event: "shepherd.state" as const, repo: opts.repo ?? "", pr, url, head_sha: opts.head ?? "", state: state ?? "pending", description };
377
448
 
378
- console.log(`notify: ${await notify(process.env.SHEPHERD_NOTIFY_WEBHOOK, event, notifyOn(process.env.SHEPHERD_NOTIFY_ON), [fileLedger(repoRoot, pr), statusLedger(opts.repo ?? "", opts.head ?? "", repoRoot)])}`);
449
+ // The variable, then ci.notify_on from the default branch, then the default: the same resolver CI uses.
450
+ const on = (() => {
451
+ try {
452
+ return ciSettings(loadPolicy(defaultBranchReader(repoRoot), ghFetch, null), process.env).notify_on.value;
453
+ } catch {
454
+ return process.env.SHEPHERD_NOTIFY_ON; // no default branch to read (a bare checkout): the variable alone
455
+ }
456
+ })();
457
+
458
+ console.log(`notify: ${await notify(process.env.SHEPHERD_NOTIFY_WEBHOOK, event, notifyOn(on), [fileLedger(repoRoot, pr), statusLedger(opts.repo ?? "", opts.head ?? "", repoRoot)])}`);
379
459
  } else if (command === "init") {
380
460
  const file = path.join(repoRoot, TEAM_FILES[0]!);
381
461
 
@@ -390,8 +470,9 @@ if (command === "install") {
390
470
  if (existsSync(file)) orExit(() => { throw new Error(`${TEAM_FILES[0]} already exists; edit it, add stack lenses with shepherd init --stacks, then run shepherd config validate`); });
391
471
  const legacy = workingTree(TEAM_FILES[1]!);
392
472
  const seed = legacy ? orExit(() => ConfigSchema.parse(parseYaml(legacy) ?? {})) : { lenses: {} };
393
- // A new repository starts review-only. A migration keeps pushing, as it did, and says so in the file; a pack keeps the pack's mode.
394
- const preset = opts.preset ?? (opts.from || seed.fixes ? undefined : legacy ? "push" : "review-only");
473
+ // Every repository starts review-only, a migration too: push needs SHEPHERD_TOKEN and lets the bot push, so it is
474
+ // opted into, never inherited. A pack or a legacy fixes: keeps its mode.
475
+ const preset = opts.preset ?? (opts.from || seed.fixes ? undefined : "review-only");
395
476
 
396
477
  const mode = Object.entries(PRESETS).find(([name]) => name === preset)?.[1];
397
478
 
@@ -401,11 +482,15 @@ if (command === "install") {
401
482
  if (opts.from) config.extends = [opts.from, ...(seed.extends ?? [])];
402
483
 
403
484
  if (mode) config.fixes = { mode };
485
+
486
+ if (opts.model) config.models = { ...config.models, loop: opts.model }; // the session model, in the reviewed policy
404
487
  const stacks = detectStacks(trackedFiles(), workingTree);
405
488
 
406
489
  mkdirSync(path.dirname(file), { recursive: true });
407
- writeFileSync(file, `# shepherd team policy. Presets: review-only (fixes.mode suggest), local-fix (local), push.\n${stringify(config)}`);
408
- console.log(`wrote ${TEAM_FILES[0]}${preset ? ` (preset ${preset})` : ""}${legacy ? ` from ${TEAM_FILES[1]} (delete it: ${TEAM_FILES[0]} now wins)` : ""}`);
490
+ writeFileSync(file, `${schemaLine(bundleVersion())}\n# shepherd team policy. Presets: review-only (fixes.mode suggest), local-fix (local), push.\n${stringify(config)}`);
491
+ console.log(`wrote ${TEAM_FILES[0]}${preset ? ` (preset ${preset})` : ""}${opts.model ? ` with models.loop ${opts.model}` : ""}${legacy ? ` from ${TEAM_FILES[1]} (delete it: ${TEAM_FILES[0]} now wins)` : ""}`);
492
+
493
+ if (legacy && !opts.preset && !seed.fixes) console.log(`${TEAM_FILES[1]} pushed fixes; this policy starts review-only. To keep pushing: rm ${TEAM_FILES[0]} && shepherd init --preset push`);
409
494
 
410
495
  // After the file exists, so a pack named by --from counts as already providing its lenses.
411
496
  if (opts.stacks) addStackLenses(file);
@@ -422,14 +507,52 @@ if (command === "install") {
422
507
 
423
508
  validate();
424
509
  console.log(`\nBefore you merge it:\n shepherd config explain --working-tree every setting and where it came from\n shepherd preview --working-tree what would run on your change, and what it can write\n${MERGE_NOTE}`);
510
+ } else if (command === "config" && sub === "schema") {
511
+ // The JSON Schema editors validate .shepherd/config.yml against; schema/config.json is this output.
512
+ console.log(JSON.stringify(configJsonSchema(), null, 2));
425
513
  } else if (command === "config" && sub === "validate") {
426
514
  validate();
427
515
  } else if (command === "config" && sub === "explain") {
428
516
  const p = policy(opts["working-tree"]);
429
517
 
430
- // Each lens's skill directory on disk, for the skills: a pinned pack lens is read from its cached copy.
431
- if (opts.json) console.log(JSON.stringify({ ...p, lenses: Object.fromEntries(Object.entries(p.lenses).map(([k, l]) => [k, { ...l, path: resolveSkill(l.value.skill, homedir(), repoRoot) }])) }, null, 2));
432
- else explain(p);
518
+ // Each lens's skill directory on disk, for the skills, so none has to search for it (an agent's glob can skip
519
+ // dot-directories such as .shepherd/): a pinned pack lens from its cached copy, a lens inside the repository from the
520
+ // default branch, never the PR checkout. A team lens that resolves nowhere fails the command.
521
+ if (opts.json) {
522
+ const lenses = Object.fromEntries(Object.entries(p.lenses).map(([k, l]) => [k, { ...l, path: lensDir(l.value.skill) }]));
523
+ const missing = Object.entries(lenses).filter(([, l]) => !l.path && l.scope !== "personal").map(([k, l]) => `lens ${k}: skill ${l.value.skill} not found${opts["working-tree"] ? "" : " on the default branch"}`);
524
+
525
+ console.log(JSON.stringify({ ...p, lenses }, null, 2));
526
+
527
+ for (const m of missing) console.error(m);
528
+
529
+ if (missing.length) process.exitCode = 1;
530
+ } else explain(p);
531
+ } else if (command === "ci-settings") {
532
+ // A job that runs no model resolves these from the default branch, so neither the PR nor the model picks them.
533
+ const settings = orExit(() => ciSettings(loadPolicy(orExit(() => defaultBranchReader(repoRoot)), ghFetch, null), process.env));
534
+
535
+ if (opts.outputs) for (const [k, v] of Object.entries(settings)) console.log(`${k}=${v.value}`);
536
+ else console.log(JSON.stringify(settings, null, 2));
537
+ } else if (command === "branding") {
538
+ // From the default branch, like the rest of the policy: a PR cannot restyle how its own review is posted.
539
+ console.log(JSON.stringify(branding(policy(opts["working-tree"])), null, 2));
540
+ } else if (command === "fanout") {
541
+ // Swarm's first wave, dispatched in one message beside the router: correctness on the whole diff and every custom
542
+ // lens whose applies_to matches a changed file, with its directory. The CLI lists them so no model skips one.
543
+ const p = policy(opts["working-tree"]);
544
+ const change = orExit(() => captureChange(repoRoot, opts.base));
545
+ const custom = preview(p, change.files).lenses.flatMap((l) => (l.files.length ? [{ lens: l.name, scope: l.files, path: lensDir(p.lenses[l.name]!.value.skill), personal: l.scope === "personal" }] : []));
546
+
547
+ const lenses = [{ lens: "correctness", scope: "full" as const, skill: "../review-correctness/SKILL.md" }, ...custom];
548
+
549
+ const missing = custom.flatMap((l) => (!l.path && !l.personal ? [`lens ${l.lens}: not found${opts["working-tree"] ? "" : " on the default branch"}`] : []));
550
+
551
+ console.log(JSON.stringify({ base_sha: change.base_sha, head_sha: change.head_sha, files: change.files, lenses }, null, 2));
552
+
553
+ for (const m of missing) console.error(m);
554
+
555
+ if (missing.length) process.exitCode = 1;
433
556
  } else if (command === "preview") {
434
557
  const p = policy(opts["working-tree"]);
435
558
  const change = orExit(() => captureChange(repoRoot, opts.base));
@@ -540,6 +663,31 @@ function policy(fromTree: boolean) {
540
663
  return p;
541
664
  }
542
665
 
666
+ /** A lens's skill directory: inside the repository, the default branch's copy unless --working-tree asks for yours. */
667
+ function lensDir(skill: string): string | null {
668
+ const inRepo = (rel: string) => !rel.startsWith("..") && !path.isAbsolute(rel);
669
+
670
+ // A bare name walks the skills directories in order, the repository's as the default branch has them: a PR can
671
+ // neither delete the team's lens nor shadow it with one of its own.
672
+ if (!opts["working-tree"] && !/[/:]/.test(skill)) {
673
+ for (const d of skillDirs(homedir(), repoRoot)) {
674
+ const rel = path.relative(repoRoot, d);
675
+ const found = inRepo(rel) ? orExit(() => defaultBranchDir(repoRoot, path.join(rel, skill))) : existsSync(path.join(d, skill, "SKILL.md")) ? path.join(d, skill) : null;
676
+
677
+ if (found) return found;
678
+ }
679
+
680
+ return null;
681
+ }
682
+
683
+ const dir = resolveSkill(skill, homedir(), repoRoot);
684
+ const rel = dir ? path.relative(repoRoot, dir) : /^[^~/][^:]*\//.test(skill) ? path.normalize(skill) : null; // a repository path the checkout may lack
685
+
686
+ if (opts["working-tree"] || rel === null || !inRepo(rel)) return dir;
687
+
688
+ return orExit(() => defaultBranchDir(repoRoot, rel));
689
+ }
690
+
543
691
  function choice(p: Effective) {
544
692
  return { ladder: p.ladder?.value ?? null, models: Object.fromEntries(Object.entries(p.models).map(([k, v]) => [k, v.value])) };
545
693
  }
@@ -582,5 +730,10 @@ function explain(p: Effective & { teamFile: string | null }): void {
582
730
 
583
731
  for (const [k, v] of Object.entries(p.recipes)) row(`recipes.${k}`, v.value.steps.join(" > "), v.source);
584
732
 
733
+ // CI settings with where each came from; secrets only as set or unset, from this shell's environment.
734
+ for (const [k, v] of Object.entries(ciSettings(p, process.env))) row(`ci.${k}`, v.value || "(none)", v.source === "variable" ? `variable ${v.variable}` : v.source);
735
+
736
+ for (const name of SECRETS) row(name, process.env[name] ? "set" : "unset", "secret");
737
+
585
738
  for (const m of p.ignored) console.log(`\nignored: ${m}`);
586
739
  }
package/src/config.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  // fill in only where the team sets none. Team files are read from the default branch, so a PR cannot change
6
6
  // the policy it is reviewed under, and a pack from another repository is pinned to a commit.
7
7
  import { execFileSync } from "node:child_process";
8
+ import { tmpdir } from "node:os";
8
9
  import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
9
10
  import path from "node:path";
10
11
  import { z } from "zod";
@@ -44,6 +45,56 @@ const FIXERS = new Set<Step>(["triage", "simplify", "ci-repair", "incident"]);
44
45
 
45
46
  const REVIEWS = new Set<Step>(["swarm", "stamp"]);
46
47
 
48
+ /**
49
+ * The glyphs shepherd posts, by role, as they are today. Not here: the `🤖 Automated comment by` header prefix, which
50
+ * triage, garden and stamp match to tell automated comments from people's, and the hidden `<!-- shepherd… -->` markers.
51
+ */
52
+ export const BRANDING = {
53
+ name: "Shepherd",
54
+ emoji: { critical: "🔴", high: "🟠", medium: "🟡", low: "🟢", nit: "⚪", blocked: "🚫", changes_needed: "⚠️", approve_with_nits: "💬", looks_good: "✅", resolved: "✅" },
55
+ } as const;
56
+
57
+ type GlyphKey = keyof typeof BRANDING.emoji;
58
+
59
+ // One short token: garden reads a severity as `**[tag]** <glyph> HIGH`, so a glyph may hold no space or markup.
60
+ const Glyph = z.string().min(1).max(16).regex(/^[^\s<>&*_`[\]\\|]+$/, "one glyph or short token: no spaces or markdown");
61
+
62
+ const Avatar = z.url({ protocol: /^https$/, error: "avatar must be an https URL" }).max(500);
63
+
64
+ // The avatar's pattern in the editor schema only: the CLI keeps the URL parser. No regex matches the parser exactly,
65
+ // so this is a subset of it: a hostname whose last label starts with a letter (never an IPv4 address the parser
66
+ // could refuse), a port up to 65535, no spaces. An editor may flag an unusual URL the CLI takes; it never passes one
67
+ // the CLI refuses.
68
+ const PORT = "(?:6553[0-5]|655[0-2]\\d|65[0-4]\\d{2}|6[0-4]\\d{3}|[1-5]\\d{4}|\\d{1,4})";
69
+
70
+ const AVATAR_PATTERN = `^https://(?:[A-Za-z0-9-]+\\.)*[A-Za-z][A-Za-z0-9-]*(?::${PORT})?(?:[/?#]\\S*)?$`;
71
+
72
+ const BrandingSchema = z
73
+ .object({
74
+ // The regex carries the trim check into the editor schema.
75
+ name: z.string().regex(/\S/, "a name, not only spaces").trim().min(1).max(40).optional(),
76
+ avatar: Avatar.optional(),
77
+ // SAFETY: the keys come from BRANDING.emoji itself, each mapped to the same optional Glyph.
78
+ emoji: z.object(Object.fromEntries(Object.keys(BRANDING.emoji).map((k) => [k, Glyph.optional()])) as Record<GlyphKey, z.ZodOptional<typeof Glyph>>).strict().optional(),
79
+ })
80
+ .strict();
81
+
82
+ // One line, so a value can never start a second GitHub Actions output when a workflow writes it.
83
+ const Line = z.string().min(1).max(500).regex(/^[^\n\r]*$/, "one line");
84
+
85
+ /** CI settings that are not secrets. Each has a repository-variable override; see CI_SETTINGS. */
86
+ const CiSchema = z
87
+ .object({
88
+ label: Line.optional(), // only PRs carrying it are shepherded automatically
89
+ aws_region: Line.optional(), // for a bedrock: model
90
+ notify_on: z.array(z.enum(["success", "failure", "pending", "error"])).min(1).optional(),
91
+ max_commits: z.number().int().min(1).max(200).optional(), // shepherd commits on one PR before a person must look
92
+ push_deny: z.array(Line).min(1).optional(), // extended regexes ADDED to the built-in list; never replaces it
93
+ incident_paths: Line.optional(), // extended regex every incident-fix path must match
94
+ audit: z.object({ plays: z.array(z.string().regex(/^[a-z0-9-]+$/)).min(1).optional(), public: z.boolean().optional() }).strict().optional(),
95
+ })
96
+ .strict();
97
+
47
98
  export const ConfigSchema = z
48
99
  .object({
49
100
  extends: z.array(z.string().min(1)).optional(),
@@ -54,6 +105,8 @@ export const ConfigSchema = z
54
105
  checks: z.record(z.string().regex(NAME), z.object({ command: z.string().min(1) }).strict()).optional(),
55
106
  fixes: z.object({ mode: z.enum(["suggest", "local", "push"]) }).strict().optional(),
56
107
  escalate: z.object({ paths: z.array(z.string().min(1)).min(1), reason: z.string().min(1).optional() }).strict().optional(),
108
+ branding: BrandingSchema.optional(), // how posted comments look; never what marks them as automated
109
+ ci: CiSchema.optional(), // CI settings; a repository variable overrides each
57
110
  recipes: z.record(z.string().regex(NAME), z.object({ steps: z.array(z.enum(STEPS)).min(1) }).strict()).optional(),
58
111
  })
59
112
  .strict();
@@ -62,6 +115,21 @@ export type Config = z.infer<typeof ConfigSchema>;
62
115
 
63
116
  export const TEAM_FILES = [".shepherd/config.yml", ".shepherd/lenses.yml"];
64
117
 
118
+ /** `.shepherd/config.yml` as JSON Schema, for editors: generated from ConfigSchema, so the two never disagree. */
119
+ export const configJsonSchema = () => ({
120
+ title: "shepherd team policy (.shepherd/config.yml)",
121
+ ...z.toJSONSchema(ConfigSchema, {
122
+ io: "input",
123
+ target: "draft-7",
124
+ override: (ctx) => {
125
+ if (ctx.zodSchema === Avatar) ctx.jsonSchema.pattern = AVATAR_PATTERN;
126
+ },
127
+ }),
128
+ });
129
+
130
+ /** The comment that points an editor at the schema of the version that wrote the file. */
131
+ export const schemaLine = (version: string) => `# yaml-language-server: $schema=https://unpkg.com/@jagreehal/shepherd@${version}/schema/config.json`;
132
+
65
133
  const BUILT_IN: Config = {
66
134
  lenses: {},
67
135
  fixes: { mode: "push" },
@@ -91,6 +159,8 @@ export type Effective = {
91
159
  checks: Record<string, Sourced<{ command: string }>>;
92
160
  fixes: Sourced<{ mode: "suggest" | "local" | "push" }>;
93
161
  escalate: Sourced<{ paths: string[]; reason?: string }> | null;
162
+ branding: Sourced<z.infer<typeof BrandingSchema>> | null;
163
+ ci: Sourced<z.infer<typeof CiSchema>> | null;
94
164
  recipes: Record<string, Sourced<{ steps: Step[] }>>;
95
165
  /** Personal settings that would change team policy, so they were not applied. */
96
166
  ignored: string[];
@@ -157,7 +227,7 @@ const pathEscapes = (rel: string) => rel.startsWith("/") || rel.split("/").inclu
157
227
 
158
228
  /** Merge layers in order: a later layer replaces a scalar and merges a map by name; a lens merges field by field. */
159
229
  function merge(layers: Layer[]): Effective {
160
- const out: Effective = { tiers: {}, ladder: null, models: {}, lenses: {}, checks: {}, fixes: { value: { mode: "push" }, source: "built-in" }, escalate: null, recipes: {}, ignored: [] };
230
+ const out: Effective = { tiers: {}, ladder: null, models: {}, lenses: {}, checks: {}, fixes: { value: { mode: "push" }, source: "built-in" }, escalate: null, branding: null, ci: null, recipes: {}, ignored: [] };
161
231
 
162
232
  for (const { source, config } of layers) {
163
233
  const tag = <T>(value: T) => ({ value, source });
@@ -168,6 +238,17 @@ function merge(layers: Layer[]): Effective {
168
238
 
169
239
  if (config.escalate) out.escalate = tag(config.escalate);
170
240
 
241
+ // A later layer sets a CI key; push_deny only ever grows, so no layer can narrow what a pack denied.
242
+ if (config.ci) {
243
+ const prev = out.ci?.value;
244
+ const deny = [...(prev?.push_deny ?? []), ...(config.ci.push_deny ?? [])];
245
+
246
+ out.ci = tag({ ...prev, ...config.ci, audit: { ...prev?.audit, ...config.ci.audit }, push_deny: deny.length ? deny : undefined });
247
+ }
248
+
249
+ // A repository can change one glyph and keep a pack's others.
250
+ if (config.branding) out.branding = tag({ ...out.branding?.value, ...config.branding, emoji: { ...out.branding?.value.emoji, ...config.branding.emoji } });
251
+
171
252
  for (const [k, v] of Object.entries(config.tiers ?? {})) out.tiers[k] = tag(v);
172
253
 
173
254
  for (const [k, v] of Object.entries(config.models ?? {})) out.models[k] = tag(v);
@@ -220,7 +301,7 @@ export function loadPolicy(read: Read, fetch: Fetch, personal: Config | null): E
220
301
  effective.lenses[k] ??= { value: v as Lens, source, scope: "personal" };
221
302
  }
222
303
 
223
- for (const key of ["extends", "checks", "fixes", "escalate", "recipes"] as const) {
304
+ for (const key of ["extends", "checks", "fixes", "escalate", "recipes", "branding", "ci"] as const) {
224
305
  if (personal[key] !== undefined) effective.ignored.push(`personal ${key}: team policy, set it in ${TEAM_FILES[0]}`);
225
306
  }
226
307
  }
@@ -446,6 +527,30 @@ export function defaultBranchReader(repoRoot: string): Read {
446
527
  };
447
528
  }
448
529
 
530
+ /**
531
+ * A skill directory as the default branch has it, extracted to a fresh temporary directory, or null when the
532
+ * branch has no SKILL.md there. A lens inside the repository must never be read from the PR checkout. Its siblings
533
+ * come from the same commit, so a `../other-skill/SKILL.md` reference still resolves; a top-level lens has none.
534
+ */
535
+ export function defaultBranchDir(repoRoot: string, rel: string): string | null {
536
+ const git = gitIn(repoRoot);
537
+ const ref = defaultBranchRef(repoRoot);
538
+
539
+ try {
540
+ git("cat-file", "-e", `${ref}:${rel}/SKILL.md`);
541
+ } catch {
542
+ return null;
543
+ }
544
+
545
+ // A fresh directory every call, outside the repository: a cached copy is one a PR's own checks could rewrite.
546
+ const dest = mkdtempSync(path.join(tmpdir(), "shepherd-lens-"));
547
+ const scope = path.dirname(rel) === "." ? rel : path.dirname(rel); // never the whole repository
548
+
549
+ execFileSync("tar", ["-x", "-C", dest], { input: execFileSync("git", ["-C", repoRoot, "archive", ref, "--", scope], { maxBuffer: 64 * 1024 * 1024 }) });
550
+
551
+ return path.join(dest, rel);
552
+ }
553
+
449
554
  /** Every file under a directory of a repository at a commit, as paths relative to that directory. */
450
555
  export type FetchDir = (owner: string, repo: string, dir: string, sha: string) => { path: string; content: string }[];
451
556
 
@@ -553,3 +658,65 @@ export const ghFetch: Fetch = (owner, repo, file, sha) => {
553
658
 
554
659
  return gh("-H", "Accept: application/vnd.github.raw", `repos/${owner}/${repo}/contents/${file}?ref=${sha}`);
555
660
  };
661
+
662
+ const html = (text: string) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
663
+
664
+ /**
665
+ * The branding skills post with, escaped for a markdown comment: `name` sits inside `**…**`, `avatar` is an `<img>`
666
+ * (or "") placed after the header prefix, and `headers` are the full first line per runner.
667
+ */
668
+ export function branding(p: Effective) {
669
+ const b = p.branding?.value;
670
+ const name = html(b?.name ?? BRANDING.name).replaceAll(/[\\`*_[\]|]/g, "\\$&");
671
+ const avatar = b?.avatar ? `<img src="${html(b.avatar)}" alt="" width="16" height="16"> ` : "";
672
+ const header = (runner: string) => `> 🤖 Automated comment by ${avatar}**${name} ${runner}**, not written by a human`;
673
+
674
+ return { name, avatar, emoji: { ...BRANDING.emoji, ...b?.emoji }, headers: { swarm: header("swarm"), incident: header("incident"), audit: header("audit") } };
675
+ }
676
+
677
+ /**
678
+ * Every CI setting that is not a secret: its repository variable, its key under `ci:`, and the built-in default.
679
+ * `push_deny` has no default here: the built-in deny list lives in the workflow, and config only adds to it.
680
+ */
681
+ export const CI_SETTINGS = {
682
+ label: { variable: "SHEPHERD_LABEL", default: "" },
683
+ aws_region: { variable: "AWS_REGION", default: "" },
684
+ notify_on: { variable: "SHEPHERD_NOTIFY_ON", default: "success,failure,error" },
685
+ max_commits: { variable: "SHEPHERD_MAX_COMMITS", default: "20" },
686
+ push_deny: { variable: null, default: "" },
687
+ incident_paths: { variable: "INCIDENT_PATHS", default: "^src/" },
688
+ audit_plays: { variable: "AUDIT_PLAYS", default: "secrets-scan sca-audit iac-security-review code-review-security" },
689
+ audit_public: { variable: "AUDIT_PUBLIC", default: "false" },
690
+ } as const;
691
+
692
+ export type CiSetting = { value: string; source: "variable" | "config" | "default"; variable: string | null };
693
+
694
+ /** The one resolver: a non-blank variable, else the default branch's `ci:`, else the default. Values are one line. */
695
+ export function ciSettings(p: Effective, env: Record<string, string | undefined>): Record<keyof typeof CI_SETTINGS, CiSetting> {
696
+ const ci = p.ci?.value;
697
+
698
+ const resolve = (key: keyof typeof CI_SETTINGS, configured: string | number | boolean | undefined): CiSetting => {
699
+ const { variable, default: fallback } = CI_SETTINGS[key];
700
+ const fromEnv = variable ? env[variable]?.trim() : undefined;
701
+ const setting: CiSetting = fromEnv ? { value: fromEnv, source: "variable", variable } : configured !== undefined ? { value: String(configured), source: "config", variable } : { value: fallback, source: "default", variable };
702
+
703
+ if (/[\n\r]/.test(setting.value)) throw new Error(`${variable ?? key}: one line only`);
704
+
705
+ // A variable skips ConfigSchema, and a cap that does not parse would let the loop run unbounded.
706
+ if (key === "max_commits" && !/^[1-9]\d{0,2}$/.test(setting.value)) throw new Error(`${variable}: a whole number from 1 to 999`);
707
+
708
+ return setting;
709
+ };
710
+
711
+ return {
712
+ label: resolve("label", ci?.label),
713
+ aws_region: resolve("aws_region", ci?.aws_region),
714
+ notify_on: resolve("notify_on", ci?.notify_on?.join(",")),
715
+ max_commits: resolve("max_commits", ci?.max_commits),
716
+ // One alternation, each pattern grouped so its own | cannot reach outside it.
717
+ push_deny: resolve("push_deny", ci?.push_deny?.map((r) => `(${r})`).join("|")),
718
+ incident_paths: resolve("incident_paths", ci?.incident_paths),
719
+ audit_plays: resolve("audit_plays", ci?.audit?.plays?.join(" ")),
720
+ audit_public: resolve("audit_public", ci?.audit?.public),
721
+ };
722
+ }
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