create-backbone-template 0.1.0

package/template/pr-slide/src/git-context.js

@@ -0,0 +1,91 @@
+import { execFileSync } from "node:child_process";
+
+import { classifyChangedFiles, inferPurpose } from "./generate-pr-deck.js";
+
+export function collectGitContext(options = {}) {
+  const repoRoot = git(process.cwd(), ["rev-parse", "--show-toplevel"]);
+  const branch = git(repoRoot, ["branch", "--show-current"]) || "HEAD";
+  const base =
+    options.base ?? detectBase(repoRoot, ["main", "master", "origin/main", "origin/master"]);
+  const mergeBase = base ? maybeGit(repoRoot, ["merge-base", "HEAD", base]) : "";
+  const committed = mergeBase ? diffNames(repoRoot, [mergeBase + "..HEAD"]) : [];
+  const staged = diffNames(repoRoot, ["--cached"]);
+  const unstaged = diffNames(repoRoot, []);
+  const untracked = gitLines(repoRoot, ["ls-files", "--others", "--exclude-standard"]);
+  const changedFiles = unique([...committed, ...staged, ...unstaged, ...untracked])
+    .filter((file) => !file.startsWith(".agents/pr-presentation/"))
+    .sort();
+  const latestSubject = maybeGit(repoRoot, ["log", "-1", "--pretty=%s"]);
+  const title = options.title ?? titleFromBranch(branch, latestSubject);
+  const purpose = options.purpose ?? inferPurpose(changedFiles);
+
+  return {
+    repoRoot,
+    title,
+    purpose,
+    branch,
+    base: base ?? "working tree",
+    generatedAt: new Date(),
+    sections: classifyChangedFiles(changedFiles),
+    changedFiles,
+  };
+}
+
+function detectBase(repoRoot, candidates) {
+  for (const candidate of candidates) {
+    if (maybeGit(repoRoot, ["rev-parse", "--verify", candidate])) {
+      return candidate;
+    }
+  }
+
+  return undefined;
+}
+
+function diffNames(repoRoot, args) {
+  const output = maybeGit(repoRoot, ["diff", "--name-only", ...args]);
+
+  return output ? output.split("\n").filter(Boolean) : [];
+}
+
+function gitLines(repoRoot, args) {
+  const output = maybeGit(repoRoot, args);
+
+  return output ? output.split("\n").filter(Boolean) : [];
+}
+
+function titleFromBranch(branch, fallback) {
+  if (branch && branch !== "HEAD") {
+    return branch
+      .replace(/^[^/]+\//, "")
+      .split(/[-_]/)
+      .filter(Boolean)
+      .map((part) => part[0].toUpperCase() + part.slice(1))
+      .join(" ");
+  }
+
+  return fallback || "Current PR";
+}
+
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+  } catch (error) {
+    if (typeof error.stdout === "string" && error.stdout.trim()) {
+      return error.stdout.trim();
+    }
+
+    throw error;
+  }
+}
+
+function maybeGit(cwd, args) {
+  try {
+    return git(cwd, args);
+  } catch {
+    return "";
+  }
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}

package/template/pr-slide/src/presentation-paths.js

@@ -0,0 +1,9 @@
+export function branchToPresentationDirName(branch) {
+  const slug = branch
+    .trim()
+    .replace(/^refs\/heads\//, "")
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return slug || "detached-head";
+}

package/template/pr-slide/src/presentations.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export function listPresentations(root) {
+  if (!existsSync(root)) {
+    return [];
+  }
+
+  return readdirSync(root)
+    .filter((name) => statSync(join(root, name)).isDirectory())
+    .map((name) => presentationFromDirectory(root, name))
+    .filter((presentation) => presentation !== undefined)
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export function resolvePresentationSlidesPath(root, name) {
+  const slidesPath = resolve(root, name, "slides.md");
+
+  if (!existsSync(slidesPath)) {
+    throw new Error(`Presentation "${name}" does not exist at ${slidesPath}`);
+  }
+
+  return slidesPath;
+}
+
+function presentationFromDirectory(root, name) {
+  const slidesPath = join(root, name, "slides.md");
+
+  if (!existsSync(slidesPath)) {
+    return undefined;
+  }
+
+  const manifest = readManifest(join(root, name, "manifest.json"));
+
+  return {
+    name,
+    title: manifest.title || name,
+    branch: manifest.branch || "",
+    slidesPath,
+  };
+}
+
+function readManifest(path) {
+  if (!existsSync(path)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return {};
+  }
+}

package/template/pr-slide/test/generate-pr-deck.test.js

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+
+import { buildDeck } from "../src/generate-pr-deck.js";
+
+describe("buildDeck", () => {
+  it("turns structural PR context into a presentation-shaped Slidev deck", () => {
+    const markdown = buildDeck({
+      title: "Hello world persistence",
+      purpose: "Teams can verify the starter path from browser to database.",
+      branch: "feature/hello-history",
+      base: "main",
+      generatedAt: new Date("2026-05-22T12:00:00.000Z"),
+      sections: {
+        pages: [
+          {
+            label: "Hello page",
+            detail: "Keeps the starter screen focused on the hello-world flow.",
+            image: "./assets/hello-page.png",
+          },
+        ],
+        behaviors: [
+          {
+            label: "The happy path gets a spotlight",
+            detail: "e2e/features/helloworld.feature",
+          },
+        ],
+        designSystem: [
+          {
+            label: "Starter component examples",
+            detail: "Keeps design-system examples free of product-specific copy.",
+          },
+        ],
+        backend: [
+          {
+            label: "Greeter service",
+            detail: "Records submitted names before returning a greeting.",
+          },
+        ],
+        database: [
+          {
+            label: "Create Hello World Inputs",
+            detail: "server/migrations/20260524160000_create_hello_world_inputs.sql",
+            migrationSummary: [
+              "Creates `hello_world_inputs`.",
+              "Stores each submitted hello-world input.",
+            ],
+          },
+        ],
+        protos: [
+          {
+            label: "Hello World",
+            detail: "proto/helloworld/v1/helloworld.proto",
+            protoServices: [
+              {
+                name: "GreeterService",
+                rpcs: [
+                  {
+                    description: "returns a greeting for the submitted name.",
+                    name: "SayHello",
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+      changedFiles: [
+        "client/src/pages/hello/hello-page.tsx",
+        "e2e/tests/helloworld.spec.ts",
+        "proto/helloworld/v1/helloworld.proto",
+      ],
+    });
+
+    expect(markdown).toContain("class=\"retro-stage");
+    expect(markdown).toContain("Prepared for the Review Committee");
+    expect(markdown).toContain("WINDOW 3.1-ish");
+    expect(markdown).toContain("<h1>Hello world persistence</h1>");
+    expect(markdown).toContain("## User-Facing Page Changes");
+    expect(markdown).toContain("./assets/hello-page.png");
+    expect(markdown).toContain("deck-screenshot");
+    expect(markdown).toContain("Hello page");
+    expect(markdown).toContain("## Features");
+    expect(markdown).toContain("Feature specification");
+    expect(markdown).not.toContain("<v-clicks>");
+    expect(markdown).toContain("Evidence");
+    expect(markdown).toContain("<h1>Technical Implementation</h1>");
+    expect(markdown).toContain("## GreeterService");
+    expect(markdown).toContain("We added this service with these RPCs:");
+    expect(markdown).toContain("SayHello");
+    expect(markdown).toContain("## Create Hello World Inputs");
+    expect(markdown).toContain("Creates `hello_world_inputs`.");
+    expect(markdown).toContain("client/src/pages/hello/hello-page.tsx");
+  });
+
+  it("keeps empty structural buckets presentation-ready", () => {
+    const markdown = buildDeck({
+      title: "Tiny docs polish",
+      purpose: "The docs read more clearly.",
+      branch: "docs/polish",
+      base: "main",
+      generatedAt: new Date("2026-05-22T12:00:00.000Z"),
+      sections: {
+        pages: [],
+        behaviors: [],
+        designSystem: [],
+        backend: [],
+        database: [],
+        protos: [],
+      },
+      changedFiles: [],
+    });
+
+    expect(markdown).toContain("No page-level UI changes detected yet.");
+    expect(markdown).toContain("No backend implementation changes detected yet.");
+    expect(markdown).toContain("No focused changed-file list was provided.");
+    expect(markdown).toContain("class=\"empty-desk\"");
+  });
+});

package/template/pr-slide/test/presentation-paths.test.js

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+
+import { branchToPresentationDirName } from "../src/presentation-paths.js";
+
+describe("branchToPresentationDirName", () => {
+  it("turns branch names into one filesystem-safe presentation directory", () => {
+    expect(branchToPresentationDirName("feat/hello-history")).toBe("feat-hello-history");
+    expect(branchToPresentationDirName("refs/heads/fix/hello copy")).toBe("fix-hello-copy");
+  });
+
+  it("falls back when Git is not on a named branch", () => {
+    expect(branchToPresentationDirName("   ")).toBe("detached-head");
+  });
+});

package/template/pr-slide/test/presentations.test.js

@@ -0,0 +1,50 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  listPresentations,
+  resolvePresentationSlidesPath,
+} from "../src/presentations.js";
+
+describe("presentations", () => {
+  it("lists directories that contain slides with manifest metadata", () => {
+    const root = mkdtempSync(join(tmpdir(), "pr-slide-"));
+    mkdirSync(join(root, "feat-one"));
+    mkdirSync(join(root, "fix-two"));
+    mkdirSync(join(root, "empty"));
+    writeFileSync(join(root, "feat-one", "slides.md"), "# One\n");
+    writeFileSync(
+      join(root, "feat-one", "manifest.json"),
+      JSON.stringify({ title: "Feature One", branch: "feat/one" }),
+    );
+    writeFileSync(join(root, "fix-two", "slides.md"), "# Two\n");
+
+    expect(listPresentations(root)).toEqual([
+      {
+        name: "feat-one",
+        title: "Feature One",
+        branch: "feat/one",
+        slidesPath: join(root, "feat-one", "slides.md"),
+      },
+      {
+        name: "fix-two",
+        title: "fix-two",
+        branch: "",
+        slidesPath: join(root, "fix-two", "slides.md"),
+      },
+    ]);
+  });
+
+  it("resolves a named presentation to its Slidev entry", () => {
+    const root = mkdtempSync(join(tmpdir(), "pr-slide-"));
+    mkdirSync(join(root, "feat-one"));
+    writeFileSync(join(root, "feat-one", "slides.md"), "# One\n");
+
+    expect(resolvePresentationSlidesPath(root, "feat-one")).toBe(
+      join(root, "feat-one", "slides.md"),
+    );
+  });
+});

package/template/proto/helloworld/v1/helloworld.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+package helloworld.v1;
+
+service GreeterService {
+  rpc SayHello(SayHelloRequest) returns (SayHelloResponse);
+}
+
+message SayHelloRequest {
+  string name = 1;
+}
+
+message SayHelloResponse {
+  string greeting = 1;
+}

package/template/scripts/run-e2e.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+eval "$(APP_ENV=test pnpm exec varlock load --format shell --compact)"
+
+if [[ "${BACKBONE_SKIP_GENERATE:-}" != "1" ]]; then
+  just generate
+fi
+
+"$@"

package/template/server/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "server"
+version = "0.1.0"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+anyhow = "1"
+axum = "0.8"
+buffa = { version = "0.5", features = ["json"] }
+buffa-types = { version = "0.5", features = ["json"] }
+connectrpc = { version = "0.4", features = ["axum"] }
+http-body = "1"
+serde = { version = "1", features = ["derive"] }
+sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "sqlite", "migrate", "macros"] }
+tokio = { version = "1", features = ["macros", "net", "rt-multi-thread", "signal"] }
+tower-http = { version = "0.6", features = ["cors", "trace"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+
+[build-dependencies]
+connectrpc-build = "0.4"

package/template/server/build.rs

@@ -0,0 +1,9 @@
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    connectrpc_build::Config::new()
+        .files(&["../proto/helloworld/v1/helloworld.proto"])
+        .includes(&["../proto"])
+        .include_file("_connectrpc.rs")
+        .compile()?;
+
+    Ok(())
+}

package/template/server/dylint/backbone_server_lints/.cargo/config.toml

@@ -0,0 +1,6 @@
+[target.'cfg(all())']
+rustflags = ["-C", "linker=dylint-link"]
+
+# For Rust versions 1.74.0 and onward, the following alternative can be used
+# (see https://github.com/rust-lang/cargo/pull/12535):
+# linker = "dylint-link"