@domesystems/templates 0.1.0

package/ai-agent-for-release-notes/guards/block-leaked-keys.json

@@ -0,0 +1,38 @@
+{
+  "json": {
+    "components": [
+      {
+        "fieldActions": [
+          {
+            "matcher": {
+              "path": "**.text",
+              "contentMatchers": [
+                {
+                  "substring": {
+                    "value": "BEGIN RSA PRIVATE KEY"
+                  }
+                },
+                {
+                  "substring": {
+                    "value": "BEGIN OPENSSH PRIVATE KEY"
+                  }
+                },
+                {
+                  "substring": {
+                    "value": "BEGIN PRIVATE KEY"
+                  }
+                },
+                {
+                  "substring": {
+                    "value": "BEGIN EC PRIVATE KEY"
+                  }
+                }
+              ]
+            },
+            "action": "FILTER_ACTION_BLOCK"
+          }
+        ]
+      }
+    ]
+  }
+}

package/ai-agent-for-release-notes/rules/release-notes.cedar

@@ -0,0 +1,49 @@
+// draft-release-notes — authorization rules
+//
+// Two kinds of boundary, which is why this template exists alongside the other
+// two. The first is the familiar one: a write tool is on the gateway and denied.
+// The second is the one MCP consolidation forces.
+//
+// GitHub replaced nine per-pull-request reads with a single `pull_request_read`
+// taking a `method` — get, get_diff, get_files, get_reviews, get_commits and
+// four more. A tool-name allow-list can only take all nine or none. Release
+// notes are written from titles, bodies and commits; the diff is the source
+// code, and there is no reason for it to reach a model. So the tool is
+// permitted and the one method is refused, on the argument.
+
+permit ( principal, action == Dome::Action::"mcp:discover", resource );
+
+permit (
+  principal,
+  action == Dome::Action::"mcp:call",
+  resource == Dome::MCPTool::"github/list_pull_requests"
+);
+
+permit (
+  principal,
+  action == Dome::Action::"mcp:call",
+  resource == Dome::MCPTool::"github/pull_request_read"
+);
+
+permit (
+  principal,
+  action == Dome::Action::"mcp:call",
+  resource == Dome::MCPTool::"github/list_commits"
+);
+
+// A forbid is the only thing that narrows the auto-generated Agent Form, which
+// permits every tool attached to the gateway.
+forbid (
+  principal,
+  action == Dome::Action::"mcp:call",
+  resource == Dome::MCPTool::"github/create_issue"
+);
+
+// Same tool as the permit above. The gateway evaluates this against the real
+// call arguments, so `method: get` is served and `method: get_diff` is refused.
+forbid (
+  principal,
+  action == Dome::Action::"mcp:call",
+  resource == Dome::MCPTool::"github/pull_request_read"
+)
+when { resource.arguments.method == "get_diff" };

package/ai-agent-for-release-notes/template.yaml

@@ -0,0 +1,155 @@
+apiVersion: templates.domesystems.ai/v1
+kind: Template
+
+metadata:
+  name: draft-release-notes
+  slug: ai-agent-for-release-notes
+  title: Draft release notes from merged pull requests
+  target_query: github ai agent release notes
+  summary: >-
+    A scheduled job that turns merged pull requests into a release-note draft.
+    It can read one repository's
+    pull requests and commits. It cannot open an issue, merge, or cut the
+    release — and it cannot read the source diff, which is the same tool it is
+    allowed to call, refused on one of its parameters.
+  domain: engineering
+  shape: scheduled-job
+  ui: run
+  business_pattern: consumes
+  governance_interest: [read-only, tool-scoped-access, argument-scoped-access]
+
+# Library-only topology and documentation data. `dome.tf` is the deployable source.
+catalog:
+  gateway:
+    name: release
+    description: Read-only GitHub surface for the release-notes job
+    default: true
+
+  connections:
+    - name: github
+      protocol: streamable-http
+      url: https://api.githubcopilot.com/mcp/
+      auth:
+        method: api-key
+        credential: shared
+        secret:
+          env: GITHUB_TOKEN
+          variable: github_token
+          label: a GitHub fine-grained personal access token
+          steps:
+            - "Create one at https://github.com/settings/personal-access-tokens/new"
+            - "Scope it to the single repository you want release notes for"
+            - "Read access to Contents and Pull requests is enough"
+            - "export GITHUB_TOKEN=github_pat_..."
+          note: "It goes into Dome, not into your app. This template never writes."
+      # `get_pull_request` used to be here and does not exist. GitHub
+      # consolidated nine per-PR reads into one `pull_request_read` taking a
+      # `method`, with no deprecated alias — and `FilterTools` drops unknown
+      # names silently, so the template would have quietly lost a tool.
+      # Verified against github/github-mcp-server, then against the live
+      # connection with `lint --live`.
+      permit:
+        - list_pull_requests
+        - pull_request_read
+        - list_commits
+      # A real write, on the gateway on purpose so the model can try it. Cedar
+      # forbids it, and a forbid beats the auto-generated Agent Form permit.
+      forbid:
+        - create_issue
+      # And the consolidation problem itself. `pull_request_read` is permitted,
+      # but one of its nine methods returns the source diff — which release
+      # notes do not need and which puts the code in the model's context. A
+      # tool-name allow-list cannot express that. Cedar on the arguments can,
+      # and the gateway enforces it on the real call, not just in `simulate`.
+      forbid_arguments:
+        - tool: pull_request_read
+          when: 'resource.arguments.method == "get_diff"'
+          why: the diff is the source code, and release notes are written from titles and commits
+          example_denied: { method: get_diff, owner: OWNER, repo: REPO, pullNumber: 1 }
+          example_allowed: { method: get, owner: OWNER, repo: REPO, pullNumber: 1 }
+
+  model:
+    name: sonnet
+    provider: anthropic
+    model_id: claude-sonnet-5
+    secret:
+      env: ANTHROPIC_API_KEY
+      variable: anthropic_api_key
+      label: an Anthropic API key
+
+  pool:
+    name: release-pool
+    default: true
+
+  agent:
+    name: release-notes-writer
+
+  rules:
+    file: rules/release-notes.cedar
+
+  guards:
+    filters:
+      - name: block-leaked-keys
+        description: Withhold a tool result carrying a private key
+        why: >-
+          Pull request bodies are prose written in a hurry, and private keys end
+          up in them. This agent pipes that prose into a model, so a leaked key
+          would be copied into a provider's context and into the draft. The
+          result is blocked rather than redacted: if a key is in the payload,
+          the right answer is that the agent does not get the payload.
+        config: guards/block-leaked-keys.json
+        bind: { tool: github, direction: response }
+
+  quotas:
+    # A headless job on a schedule is the thing most likely to run away
+    # unnoticed, so the cap is tighter than the interactive templates'.
+    - subject: agent
+      agent: release-notes-writer
+      unit: dome_usd
+      limit: 2
+      window: daily
+      name: release-notes-writer daily spend
+    # Counted in calls, not dollars, because what goes wrong with a repository
+    # crawl is a rate limit rather than a bill.
+    - subject: tool-connection
+      connection: github
+      unit: calls
+      limit: 1000
+      window: daily
+      name: github calls per day
+
+app:
+  runtime:
+    pattern: run
+    language: python
+  agent:
+    prompt: app/instructions.md
+    help: app/help.md
+    # The run surface uses the first starter as its task prompt, and `${VAR}`
+    # is filled from the declared run parameters below. Without the repo in
+    # here the agent was told it would be "given the run parameters" and then
+    # given nothing.
+    starters:
+      - Draft release notes for pull requests merged into ${TARGET_REPO} in the
+        14 days before ${TODAY}.
+    model: claude-sonnet-5
+    max_tokens: 8192
+    skills:
+      - name: draft-release-notes
+        description: Read merged pull requests in a window and write user-facing notes.
+        tools:
+          - github/list_pull_requests
+          - github/pull_request_read
+          - github/list_commits
+          - github/create_issue
+    invoker:
+      kind: cron
+      schedule: "0 9 * * MON"
+  options:
+    identity:
+      mode: none
+    # Run parameters. `${VAR}` in a starter, prompt or help file is filled from
+    # these; the label is what `.env.example` tells the reader to put there.
+    env:
+      - name: TARGET_REPO
+        label: "the repository to draft notes for, as owner/repo — your choice, and the token must reach it"

package/bin/dome-templates.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.mjs";
+
+main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@domesystems/templates",
+  "version": "0.1.0",
+  "description": "Initialize and run Dome governed-agent templates.",
+  "type": "module",
+  "bin": {
+    "dome-templates": "bin/dome-templates.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "ai-agent-for-documentation",
+    "ai-agent-for-notion",
+    "ai-agent-for-release-notes"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "validate": "node scripts/validate-templates.mjs",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "yaml": "2.9.0"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { readManifest } from "./manifest.mjs";
+import { imageForRuntime, renderCompose } from "./runtime.mjs";
+import { copyTemplate, initializeEnvironment } from "./template-files.mjs";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function usage() {
+  return `Usage:\n  npx @domesystems/templates init <template> [--dir <directory>] [--force]\n  npx @domesystems/templates up <template> [--dir <directory>] [--skip-provision] [--no-start] [--detach] [--force]\n\nCommands:\n  init  Copy a template locally and create .env from .env.example.\n  up    Initialize (when needed), generate Compose from template.yaml, provision Dome, and start it.\n\nThe generated .dome-compose.yaml is ignored by Git. Runtime images are selected\nfrom app.runtime.language and app.runtime.pattern in template.yaml.\n`;
+}
+
+function fail(message) {
+  throw new Error(`${message}\n\n${usage()}`);
+}
+
+function parseArguments(argv) {
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) return { help: true };
+  const [command, slug, ...rest] = argv;
+  const options = { force: false, provision: true, start: true, detach: false, directory: undefined };
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index];
+    if (argument === "--force") options.force = true;
+    else if (argument === "--skip-provision") options.provision = false;
+    else if (argument === "--no-start") options.start = false;
+    else if (argument === "--detach") options.detach = true;
+    else if (argument === "--dir") {
+      options.directory = rest[index + 1];
+      if (!options.directory) fail("--dir requires a directory.");
+      index += 1;
+    } else {
+      fail(`Unknown option: ${argument}`);
+    }
+  }
+  if (!["init", "up"].includes(command)) fail(`Unknown command: ${command}`);
+  if (!slug) fail("A template slug is required.");
+  return { command, slug, options };
+}
+
+function templateSource(slug) {
+  if (slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") {
+    fail(`Invalid template slug: ${slug}`);
+  }
+  const source = path.join(packageRoot, slug);
+  if (!fs.statSync(path.join(source, "template.yaml"), { throwIfNoEntry: false })?.isFile()) {
+    fail(`Unknown template: ${slug}`);
+  }
+  return source;
+}
+
+function targetDirectory(slug, directory) {
+  return path.resolve(process.cwd(), directory ?? slug);
+}
+
+function isEmpty(directory) {
+  return !fs.existsSync(directory) || fs.readdirSync(directory).length === 0;
+}
+
+function init(slug, options, output) {
+  const source = templateSource(slug);
+  const target = targetDirectory(slug, options.directory);
+  if (!isEmpty(target) && !options.force) {
+    throw new Error(`${target} already exists and is not empty. Choose --dir or pass --force.`);
+  }
+  copyTemplate(source, target);
+  const environmentCreated = initializeEnvironment(target);
+  output(`Initialized ${slug} in ${target}.`);
+  if (environmentCreated) output("Created .env from .env.example. Add the required values before a live run.");
+  return target;
+}
+
+function resolveUpDirectory(slug, options, output) {
+  const target = targetDirectory(slug, options.directory);
+  if (fs.statSync(path.join(target, "template.yaml"), { throwIfNoEntry: false })?.isFile()) return target;
+  return init(slug, options, output);
+}
+
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+  if (result.error) throw new Error(`Could not run ${command}: ${result.error.message}`);
+  if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} exited with status ${result.status}.`);
+}
+
+export function main(argv, { output = console.log, error = console.error } = {}) {
+  try {
+    const parsed = parseArguments(argv);
+    if (parsed.help) {
+      output(usage());
+      return;
+    }
+    const { command, slug, options } = parsed;
+    if (command === "init") {
+      init(slug, options, output);
+      return;
+    }
+
+    const target = resolveUpDirectory(slug, options, output);
+    const manifest = readManifest(target);
+    const composePath = path.join(target, ".dome-compose.yaml");
+    fs.writeFileSync(composePath, renderCompose(manifest.app.runtime));
+    output(`Generated ${path.basename(composePath)} using ${imageForRuntime(manifest.app.runtime)}.`);
+
+    if (options.provision) run("dome", ["import", "dome.tf"], target);
+    if (options.start) {
+      const args = ["compose", "-f", ".dome-compose.yaml", "up"];
+      if (options.detach) args.push("--detach");
+      run("docker", args, target);
+    }
+    if (!options.provision || !options.start) {
+      output("Skipped requested steps. Re-run without --skip-provision or --no-start when ready.");
+    }
+  } catch (caught) {
+    error(`Error: ${caught.message}`);
+    process.exitCode = 1;
+  }
+}

package/src/manifest.mjs

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseDocument } from "yaml";
+
+export function readManifest(templateDirectory) {
+  const manifestPath = path.join(templateDirectory, "template.yaml");
+  if (!fs.statSync(manifestPath, { throwIfNoEntry: false })?.isFile()) {
+    throw new Error(`No template.yaml found in ${templateDirectory}.`);
+  }
+
+  const document = parseDocument(fs.readFileSync(manifestPath, "utf8"));
+  if (document.errors.length) {
+    throw new Error(`Invalid template.yaml: ${document.errors.map((error) => error.message).join("; ")}`);
+  }
+
+  const manifest = document.toJS() ?? {};
+  const runtime = manifest.app?.runtime;
+  if (!runtime?.pattern || !runtime?.language) {
+    throw new Error("template.yaml must declare app.runtime.pattern and app.runtime.language.");
+  }
+  return manifest;
+}

package/src/runtime.mjs

@@ -0,0 +1,22 @@
+const runtimeImages = {
+  "python:chat": "ghcr.io/dome-systems/runtime-py-chat",
+  "typescript:chat": "ghcr.io/dome-systems/runtime-ts-chat",
+  "python:run": "ghcr.io/dome-systems/runtime-py-run",
+  "typescript:run": "ghcr.io/dome-systems/runtime-ts-run",
+};
+
+export function imageForRuntime(runtime) {
+  if (runtime.image) return runtime.image;
+  const key = `${runtime.language}:${runtime.pattern}`;
+  const image = runtimeImages[key];
+  if (!image) {
+    const supported = Object.keys(runtimeImages).join(", ");
+    throw new Error(`Unsupported runtime ${key}. Set app.runtime.image explicitly, or use one of: ${supported}.`);
+  }
+  return `${image}:${runtime.image_tag ?? "latest"}`;
+}
+
+export function renderCompose(runtime) {
+  const image = imageForRuntime(runtime);
+  return `# Generated by @domesystems/templates. Do not edit; update template.yaml instead.\nservices:\n  app:\n    image: ${image}\n    env_file: .env\n    volumes:\n      - ./app:/config:ro\n    ports:\n      - \"3000:3000\"\n    healthcheck:\n      test: [\"CMD\", \"python\", \"-c\", \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:3000/health', timeout=2)\"]\n      interval: 30s\n      timeout: 3s\n      start_period: 10s\n      retries: 3\n`;
+}

package/src/template-files.mjs

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const excludedNames = new Set([".env", ".git", ".terraform", "node_modules", "docker-compose.yml", ".dome-compose.yaml"]);
+
+export function copyTemplate(source, destination) {
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    if (excludedNames.has(entry.name)) continue;
+    const from = path.join(source, entry.name);
+    const to = path.join(destination, entry.name);
+    if (entry.isDirectory()) {
+      copyTemplate(from, to);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+export function initializeEnvironment(templateDirectory) {
+  const example = path.join(templateDirectory, ".env.example");
+  const environment = path.join(templateDirectory, ".env");
+  if (fs.statSync(example, { throwIfNoEntry: false })?.isFile() && !fs.existsSync(environment)) {
+    fs.copyFileSync(example, environment);
+    return true;
+  }
+  return false;
+}