@jagreehal/shepherd 0.6.0 → 0.8.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,20 @@
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 summary <round.json> [--previous <comment.md>] [--body] (Markdown: swarm's summary comment)
19
+ // shepherd branding [--working-tree] (JSON: the name, avatar, glyphs and headers posted comments use)
20
+ // shepherd ci-settings [--outputs] (the CI settings from variables, the default branch's ci:, defaults)
21
+ // shepherd fanout [--base <ref>] [--working-tree] (JSON: the lenses swarm starts beside the router, each with its scope)
17
22
  // shepherd preview [--recipe <name>] [--base <ref>] [--working-tree] (what would run on your change)
18
23
  // shepherd doctor [--json] (is this machine and repository set up? each problem says what to do)
19
24
  // shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>... (run it; check it kept to the mode)
20
25
  // shepherd trace event <stage> <start|end> --pr <n> [--round <n>] [--outcome ok|failed|skipped] [--retries <n>] [--head <sha>]
21
26
  // 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)
27
+ // 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
28
  // shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>
24
29
  // 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
30
  //
@@ -36,20 +41,24 @@ import path from "node:path";
36
41
  import { parseArgs } from "node:util";
37
42
  import { parse as parseYaml, stringify } from "yaml";
38
43
  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";
44
+ 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";
45
+ import { renderSummary } from "./summary.ts";
40
46
  import { ghThreads, snapshot, verdict } from "./acceptance.ts";
41
47
  import { doctor } from "./doctor.ts";
42
48
  import { fileLedger, notify, notifyOn, STATES, statusLedger } from "./notify.ts";
43
49
  import { collect, collectEscapes, score } from "./garden.ts";
44
50
  import { collectTraces, tempoHeaders, traceLimits, traceScores } from "./garden-traces.ts";
45
- import { install, type Outcome, pinWorkflow, uninstall } from "./install.ts";
51
+ import { environmentWorkflow, install, type Outcome, pinWorkflow, uninstall, upgradeWorkflow } from "./install.ts";
46
52
  import { buildDemo, captureChange, demoBugs, finish, receiptStatus } from "./local.ts";
47
53
  import { prStack } from "./stack.ts";
48
54
  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";
55
+ 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
56
 
51
57
  const BUNDLE_ROOT = path.resolve(import.meta.dir, "..");
52
58
 
59
+ /** This CLI's version: workflows and the policy's schema line pin to it. */
60
+ const bundleVersion = () => z.object({ version: z.string() }).parse(JSON.parse(readFileSync(path.join(BUNDLE_ROOT, "package.json"), "utf8"))).version;
61
+
53
62
  const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [--force]
54
63
  shepherd uninstall [--project | --target <dir>]
55
64
  shepherd lens new <name> [--from <template>] [--applies <glob>]... [--description <text>]
@@ -63,9 +72,14 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
63
72
  shepherd local finish <record.json> [--base <ref>]
64
73
  shepherd local status [--base <ref>]
65
74
  shepherd local demo [<dir>]
66
- shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks]
75
+ shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks] [--model <id>]
67
76
  shepherd config validate
77
+ shepherd config schema
68
78
  shepherd config explain [--json] [--working-tree]
79
+ shepherd summary <round.json> [--previous <comment.md>] [--body]
80
+ shepherd branding [--working-tree]
81
+ shepherd ci-settings [--outputs]
82
+ shepherd fanout [--base <ref>] [--working-tree]
69
83
  shepherd preview [--recipe <name>] [--base <ref>] [--working-tree]
70
84
  shepherd doctor [--json]
71
85
  shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>...
@@ -73,7 +87,7 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
73
87
  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
88
  shepherd stack <pr>
75
89
  shepherd model-id <provider:model | provider/model>
76
- shepherd workflows [--audit]
90
+ shepherd workflows [--audit] [--upgrade] [--model <id>] [--environment <name>] [--label <name>] [--aws-region <region>]
77
91
  shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>`;
78
92
 
79
93
  const { values: opts, positionals } = parseArgs({
@@ -87,7 +101,9 @@ const { values: opts, positionals } = parseArgs({
87
101
  applies: { type: "string", multiple: true },
88
102
  description: { type: "string" },
89
103
  global: { type: "boolean", default: false },
90
- model: { type: "string" },
104
+ model: { type: "string" }, // lens add: the lens's model; init, workflows: the session model, written to models.loop
105
+ environment: { type: "string" }, // workflows: the GitHub environment whose secrets hold the model keys
106
+ upgrade: { type: "boolean", default: false }, // workflows: rewrite existing workflows from the current templates
91
107
  since: { type: "string" },
92
108
  file: { type: "string" }, // opencode-agents: a lenses.yml to read instead of the default branch's
93
109
  "min-prs": { type: "string", default: "3" },
@@ -99,10 +115,15 @@ const { values: opts, positionals } = parseArgs({
99
115
  base: { type: "string" }, // local: the ref the change is measured from
100
116
  from: { type: "string" }, // lens new: a starter lens in lenses/; init: the pack to extend
101
117
  json: { type: "boolean", default: false },
118
+ previous: { type: "string" }, // summary: the summary comment already on the PR, whose rounds carry forward
119
+ body: { type: "boolean", default: false }, // summary: no marker or header, for the handoff findings.md
102
120
  "working-tree": { type: "boolean", default: false }, // explain, preview: your edits instead of the default branch
103
121
  recipe: { type: "string" },
104
122
  preset: { type: "string" }, // init: how far fixes go
105
123
  audit: { type: "boolean", default: false }, // workflows: also the scheduled OWASP playbook audit
124
+ outputs: { type: "boolean", default: false }, // ci-settings: key=value lines for $GITHUB_OUTPUT
125
+ label: { type: "string" }, // workflows: ci.label, the handoff label
126
+ "aws-region": { type: "string" }, // workflows: ci.aws_region, for a bedrock: model
106
127
  stacks: { type: "boolean", default: false }, // init: add a lens for each stack the repository uses
107
128
  pr: { type: "string" }, // acceptance: the PR whose threads must stay as they were; trace: the PR
108
129
  round: { type: "string" }, // trace: the quality-loop round
@@ -149,6 +170,9 @@ const orExit = <T>(run: () => T): T => {
149
170
  }
150
171
  };
151
172
 
173
+ // Secrets config explain shows only as set or unset.
174
+ const SECRETS = ["SHEPHERD_TOKEN", "SHEPHERD_API_KEY", "SHEPHERD_NOTIFY_WEBHOOK", ...new Set(PROVIDER_KEY_ENVS)];
175
+
152
176
  const MERGE_NOTE = "shepherd reads .shepherd/ from the default branch: commit and merge it before it takes effect.";
153
177
 
154
178
  if (command === "install") {
@@ -330,7 +354,7 @@ if (command === "install") {
330
354
  const { model, source } = ciModel(p, process.env.SHEPHERD_MODEL || undefined);
331
355
  const session = opencodeModel(model);
332
356
 
333
- const opencode = opencodeAgents(choice(p));
357
+ const opencode = ciOpencodeConfig(session, choice(p));
334
358
  // Every key the plan's models read, so the workflow can drop the rest before the model runs.
335
359
  const keyEnvs = [...new Set([session, ...Object.values(opencode.agent).map((a) => a.model)].flatMap((m) => providerKeyEnv(m) ?? []))].sort();
336
360
 
@@ -349,19 +373,71 @@ if (command === "install") {
349
373
  for (const name of ["shepherd.yml", "shepherd-incident.yml", ...(opts.audit ? ["shepherd-audit.yml"] : [])]) {
350
374
  const to = path.join(dest, name);
351
375
 
376
+ // Pin the workflow to the version that wrote it, so its skills match this CLI.
377
+ const version = bundleVersion();
378
+
379
+ if (existsSync(to) && opts.upgrade) {
380
+ const upgraded = orExit(() => upgradeWorkflow(readFileSync(path.join(BUNDLE_ROOT, "templates", name), "utf8"), readFileSync(to, "utf8"), version, opts.environment));
381
+
382
+ writeFileSync(to, upgraded.text);
383
+ console.log(`upgraded .github/workflows/${name} to ${version}${upgraded.kept.length ? ` (kept ${upgraded.kept.join(", ")})` : ""}`);
384
+ continue;
385
+ }
386
+
352
387
  if (existsSync(to)) {
353
- console.log(`kept .github/workflows/${name} (exists)`);
388
+ const kept = readFileSync(to, "utf8");
389
+ const scoped = opts.environment ? orExit(() => environmentWorkflow(kept, opts.environment!)) : kept;
390
+
391
+ // --environment on a rerun still scopes the model job: fill the template's placeholder, or say what to change.
392
+ if (scoped !== kept) {
393
+ writeFileSync(to, scoped);
394
+ console.log(`scoped .github/workflows/${name} to the ${opts.environment} environment`);
395
+ } else if (opts.environment && !kept.includes(`environment: ${opts.environment}`)) {
396
+ console.log(`kept .github/workflows/${name} (exists): add \`environment: ${opts.environment}\` to its model job by hand`);
397
+ } else console.log(`kept .github/workflows/${name} (exists): run \`shepherd workflows --upgrade\` to update it`);
398
+
354
399
  continue;
355
400
  }
356
401
 
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;
402
+ const text = pinWorkflow(readFileSync(path.join(BUNDLE_ROOT, "templates", name), "utf8"), version);
359
403
 
360
- writeFileSync(to, pinWorkflow(readFileSync(path.join(BUNDLE_ROOT, "templates", name), "utf8"), version));
404
+ writeFileSync(to, opts.environment ? orExit(() => environmentWorkflow(text, opts.environment!)) : text);
361
405
  console.log(`wrote .github/workflows/${name}`);
362
406
  }
363
407
 
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).");
408
+ // Settings go in the team policy, reviewed and versioned, rather than in repository variables.
409
+ if (opts.model) {
410
+ orExit(() => pinModel(repoLensFile(repoRoot), "loop", opts.model!));
411
+ console.log(`pinned models.loop: ${opts.model} in ${path.relative(repoRoot, repoLensFile(repoRoot))}`);
412
+ }
413
+
414
+ const ci: Record<string, string> = {};
415
+
416
+ if (opts.label) ci.label = opts.label;
417
+
418
+ if (opts["aws-region"]) ci.aws_region = opts["aws-region"];
419
+
420
+ if (Object.keys(ci).length) {
421
+ orExit(() => setCi(repoLensFile(repoRoot), ci));
422
+ console.log(`set ${Object.entries(ci).map(([k, v]) => `ci.${k}: ${v}`).join(", ")} in ${path.relative(repoRoot, repoLensFile(repoRoot))}`);
423
+ }
424
+
425
+ 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)";
426
+ 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";
427
+
428
+ // SHEPHERD_TOKEN only pushes fixes: ask for it only when the policy pushes.
429
+ const pushes = (() => {
430
+ try {
431
+ return loadPolicy(workingTree, ghFetch, null).fixes.value.mode === "push";
432
+ } catch {
433
+ return true; // a policy that does not load yet: name the token rather than leave it out
434
+ }
435
+ })();
436
+
437
+ const token = pushes ? "add SHEPHERD_TOKEN as a repository secret and " : "";
438
+ const later = pushes ? "" : "SHEPHERD_TOKEN is not needed until fixes.mode is push.\n";
439
+
440
+ 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
441
  } else if (command === "notify") {
366
442
  const pr = Number(opts.pr);
367
443
  const state = STATES.find((s) => s === opts.state);
@@ -375,7 +451,16 @@ if (command === "install") {
375
451
  const url = `${process.env.GITHUB_SERVER_URL || "https://github.com"}/${opts.repo}/pull/${pr}`;
376
452
  const event = { event: "shepherd.state" as const, repo: opts.repo ?? "", pr, url, head_sha: opts.head ?? "", state: state ?? "pending", description };
377
453
 
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)])}`);
454
+ // The variable, then ci.notify_on from the default branch, then the default: the same resolver CI uses.
455
+ const on = (() => {
456
+ try {
457
+ return ciSettings(loadPolicy(defaultBranchReader(repoRoot), ghFetch, null), process.env).notify_on.value;
458
+ } catch {
459
+ return process.env.SHEPHERD_NOTIFY_ON; // no default branch to read (a bare checkout): the variable alone
460
+ }
461
+ })();
462
+
463
+ console.log(`notify: ${await notify(process.env.SHEPHERD_NOTIFY_WEBHOOK, event, notifyOn(on), [fileLedger(repoRoot, pr), statusLedger(opts.repo ?? "", opts.head ?? "", repoRoot)])}`);
379
464
  } else if (command === "init") {
380
465
  const file = path.join(repoRoot, TEAM_FILES[0]!);
381
466
 
@@ -390,8 +475,9 @@ if (command === "install") {
390
475
  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
476
  const legacy = workingTree(TEAM_FILES[1]!);
392
477
  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");
478
+ // Every repository starts review-only, a migration too: push needs SHEPHERD_TOKEN and lets the bot push, so it is
479
+ // opted into, never inherited. A pack or a legacy fixes: keeps its mode.
480
+ const preset = opts.preset ?? (opts.from || seed.fixes ? undefined : "review-only");
395
481
 
396
482
  const mode = Object.entries(PRESETS).find(([name]) => name === preset)?.[1];
397
483
 
@@ -401,11 +487,15 @@ if (command === "install") {
401
487
  if (opts.from) config.extends = [opts.from, ...(seed.extends ?? [])];
402
488
 
403
489
  if (mode) config.fixes = { mode };
490
+
491
+ if (opts.model) config.models = { ...config.models, loop: opts.model }; // the session model, in the reviewed policy
404
492
  const stacks = detectStacks(trackedFiles(), workingTree);
405
493
 
406
494
  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)` : ""}`);
495
+ writeFileSync(file, `${schemaLine(bundleVersion())}\n# shepherd team policy. Presets: review-only (fixes.mode suggest), local-fix (local), push.\n${stringify(config)}`);
496
+ 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)` : ""}`);
497
+
498
+ 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
499
 
410
500
  // After the file exists, so a pack named by --from counts as already providing its lenses.
411
501
  if (opts.stacks) addStackLenses(file);
@@ -422,14 +512,59 @@ if (command === "install") {
422
512
 
423
513
  validate();
424
514
  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}`);
515
+ } else if (command === "config" && sub === "schema") {
516
+ // The JSON Schema editors validate .shepherd/config.yml against; schema/config.json is this output.
517
+ console.log(JSON.stringify(configJsonSchema(), null, 2));
425
518
  } else if (command === "config" && sub === "validate") {
426
519
  validate();
427
520
  } else if (command === "config" && sub === "explain") {
428
521
  const p = policy(opts["working-tree"]);
429
522
 
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);
523
+ // Each lens's skill directory on disk, for the skills, so none has to search for it (an agent's glob can skip
524
+ // dot-directories such as .shepherd/): a pinned pack lens from its cached copy, a lens inside the repository from the
525
+ // default branch, never the PR checkout. A team lens that resolves nowhere fails the command.
526
+ if (opts.json) {
527
+ const lenses = Object.fromEntries(Object.entries(p.lenses).map(([k, l]) => [k, { ...l, path: lensDir(l.value.skill) }]));
528
+ 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"}`);
529
+
530
+ console.log(JSON.stringify({ ...p, lenses }, null, 2));
531
+
532
+ for (const m of missing) console.error(m);
533
+
534
+ if (missing.length) process.exitCode = 1;
535
+ } else explain(p);
536
+ } else if (command === "ci-settings") {
537
+ // A job that runs no model resolves these from the default branch, so neither the PR nor the model picks them.
538
+ const settings = orExit(() => ciSettings(loadPolicy(orExit(() => defaultBranchReader(repoRoot)), ghFetch, null), process.env));
539
+
540
+ if (opts.outputs) for (const [k, v] of Object.entries(settings)) console.log(`${k}=${v.value}`);
541
+ else console.log(JSON.stringify(settings, null, 2));
542
+ } else if (command === "branding") {
543
+ // From the default branch, like the rest of the policy: a PR cannot restyle how its own review is posted.
544
+ console.log(JSON.stringify(branding(policy(opts["working-tree"])), null, 2));
545
+ } else if (command === "summary" && sub) {
546
+ // Swarm's summary comment, rendered from the round's JSON.
547
+ const input = orExit(() => JSON.parse(readFileSync(sub, "utf8")));
548
+ const b = branding(policy(opts["working-tree"]));
549
+ const previous = opts.previous ? readFileSync(opts.previous, "utf8") : undefined;
550
+
551
+ process.stdout.write(orExit(() => renderSummary(input, b.emoji, opts.body ? null : b.headers.swarm, previous)));
552
+ } else if (command === "fanout") {
553
+ // Swarm's first wave, dispatched in one message beside the router: correctness on the whole diff and every custom
554
+ // lens whose applies_to matches a changed file, with its directory. The CLI lists them so no model skips one.
555
+ const p = policy(opts["working-tree"]);
556
+ const change = orExit(() => captureChange(repoRoot, opts.base));
557
+ 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" }] : []));
558
+
559
+ const lenses = [{ lens: "correctness", scope: "full" as const, skill: "../review-correctness/SKILL.md" }, ...custom];
560
+
561
+ const missing = custom.flatMap((l) => (!l.path && !l.personal ? [`lens ${l.lens}: not found${opts["working-tree"] ? "" : " on the default branch"}`] : []));
562
+
563
+ console.log(JSON.stringify({ base_sha: change.base_sha, head_sha: change.head_sha, files: change.files, lenses }, null, 2));
564
+
565
+ for (const m of missing) console.error(m);
566
+
567
+ if (missing.length) process.exitCode = 1;
433
568
  } else if (command === "preview") {
434
569
  const p = policy(opts["working-tree"]);
435
570
  const change = orExit(() => captureChange(repoRoot, opts.base));
@@ -540,6 +675,31 @@ function policy(fromTree: boolean) {
540
675
  return p;
541
676
  }
542
677
 
678
+ /** A lens's skill directory: inside the repository, the default branch's copy unless --working-tree asks for yours. */
679
+ function lensDir(skill: string): string | null {
680
+ const inRepo = (rel: string) => !rel.startsWith("..") && !path.isAbsolute(rel);
681
+
682
+ // A bare name walks the skills directories in order, the repository's as the default branch has them: a PR can
683
+ // neither delete the team's lens nor shadow it with one of its own.
684
+ if (!opts["working-tree"] && !/[/:]/.test(skill)) {
685
+ for (const d of skillDirs(homedir(), repoRoot)) {
686
+ const rel = path.relative(repoRoot, d);
687
+ const found = inRepo(rel) ? orExit(() => defaultBranchDir(repoRoot, path.join(rel, skill))) : existsSync(path.join(d, skill, "SKILL.md")) ? path.join(d, skill) : null;
688
+
689
+ if (found) return found;
690
+ }
691
+
692
+ return null;
693
+ }
694
+
695
+ const dir = resolveSkill(skill, homedir(), repoRoot);
696
+ const rel = dir ? path.relative(repoRoot, dir) : /^[^~/][^:]*\//.test(skill) ? path.normalize(skill) : null; // a repository path the checkout may lack
697
+
698
+ if (opts["working-tree"] || rel === null || !inRepo(rel)) return dir;
699
+
700
+ return orExit(() => defaultBranchDir(repoRoot, rel));
701
+ }
702
+
543
703
  function choice(p: Effective) {
544
704
  return { ladder: p.ladder?.value ?? null, models: Object.fromEntries(Object.entries(p.models).map(([k, v]) => [k, v.value])) };
545
705
  }
@@ -582,5 +742,10 @@ function explain(p: Effective & { teamFile: string | null }): void {
582
742
 
583
743
  for (const [k, v] of Object.entries(p.recipes)) row(`recipes.${k}`, v.value.steps.join(" > "), v.source);
584
744
 
745
+ // CI settings with where each came from; secrets only as set or unset, from this shell's environment.
746
+ 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);
747
+
748
+ for (const name of SECRETS) row(name, process.env[name] ? "set" : "unset", "secret");
749
+
585
750
  for (const m of p.ignored) console.log(`\nignored: ${m}`);
586
751
  }
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
+ }