@starterculture/devkeep-actions 0.0.1

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026 StarterCulture. All rights reserved.
+
+This package is published solely so that Devkeep's own GitHub Actions
+workflows can install and run it. No licence is granted to use, copy,
+modify, distribute, or create derivative works from it for any other
+purpose.
+
+Publishing it to a public registry is a distribution mechanism, not a
+grant of rights: a GitHub Actions runner is an ephemeral machine that can
+only obtain code by fetching it from somewhere publicly readable, and
+there is no way to make that fetch work for a repository owner without
+making the artifact itself fetchable. Its being downloadable is a
+consequence of that, and nothing more.

package/README.md

@@ -0,0 +1,16 @@
+# @starterculture/devkeep-actions
+
+Bundled entrypoints that Devkeep's GitHub Actions workflows install and
+run on a CI runner.
+
+This is an internal runtime component, not a library. It has no stable
+public API, no documented interface, and no standalone use: each bundle
+expects a specific set of environment variables supplied by the workflow
+that invokes it, and writes its output to a Devkeep vault repository.
+Contents and behaviour may change without notice between versions.
+
+It is published to a public registry for one reason: a GitHub Actions
+runner is an ephemeral machine that can only obtain code by fetching it
+from somewhere publicly readable.
+
+Licence: see LICENSE. All rights reserved.

package/dist/consolidate-release.js

@@ -0,0 +1,450 @@
+#!/usr/bin/env node
+
+// ../../modules/core/dist/github/client.js
+import { Octokit } from "@octokit/rest";
+function createGithubClient(token) {
+  if (!token) {
+    throw new Error("GitHub token is required");
+  }
+  return new Octokit({ auth: token });
+}
+
+// ../../modules/core/dist/github/retryOnConflict.js
+async function retryOnConflict(attempt, maxAttempts = 3) {
+  for (let tryNumber = 1; ; tryNumber++) {
+    try {
+      return await attempt();
+    } catch (error) {
+      const status = error.status;
+      if (tryNumber >= maxAttempts || status !== 409 && status !== 422) {
+        throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 300 * tryNumber));
+    }
+  }
+}
+
+// ../../modules/core/dist/tokenUsage.js
+var ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
+function addTokenUsage(a, b) {
+  return { inputTokens: a.inputTokens + b.inputTokens, outputTokens: a.outputTokens + b.outputTokens };
+}
+
+// ../../modules/core/dist/rollover.js
+var ZERO_ROLLOVER_USAGE = {
+  today: { key: "", usage: ZERO_USAGE },
+  month: { key: "", usage: ZERO_USAGE }
+};
+function todayKey(now = /* @__PURE__ */ new Date()) {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function monthKey(now = /* @__PURE__ */ new Date()) {
+  return todayKey(now).slice(0, 7);
+}
+function addRolloverUsage(current, delta, now = /* @__PURE__ */ new Date()) {
+  const nowTodayKey = todayKey(now);
+  const nowMonthKey = monthKey(now);
+  return {
+    today: {
+      key: nowTodayKey,
+      usage: addTokenUsage(current.today.key === nowTodayKey ? current.today.usage : ZERO_USAGE, delta)
+    },
+    month: {
+      key: nowMonthKey,
+      usage: addTokenUsage(current.month.key === nowMonthKey ? current.month.usage : ZERO_USAGE, delta)
+    }
+  };
+}
+
+// ../../modules/core/dist/claude/client.js
+import Anthropic from "@anthropic-ai/sdk";
+function createClaudeClient(apiKey) {
+  const key = apiKey ?? process.env.ANTHROPIC_API_KEY;
+  if (!key) {
+    throw new Error("ANTHROPIC_API_KEY is not set");
+  }
+  return new Anthropic({ apiKey: key });
+}
+
+// ../../modules/core/dist/claude/complete.js
+var DEFAULT_MAX_CONTINUATIONS = 5;
+var CONTINUATION_USER_MESSAGE = "Continue exactly where you left off. Do not repeat any text already written, and do not add any preamble or commentary \u2014 resume the previous response verbatim from the exact cutoff point.";
+async function createCompleteMessage(claude, params, { maxContinuations = DEFAULT_MAX_CONTINUATIONS, timeoutMs, signal } = {}) {
+  let fullText = "";
+  let usage = ZERO_USAGE;
+  const requestOptions = timeoutMs !== void 0 || signal !== void 0 ? { timeout: timeoutMs, signal } : void 0;
+  for (let attempt = 0; attempt <= maxContinuations; attempt++) {
+    const messages = fullText ? [
+      ...params.messages,
+      { role: "assistant", content: fullText },
+      { role: "user", content: CONTINUATION_USER_MESSAGE }
+    ] : params.messages;
+    const message = requestOptions ? await claude.messages.create({ ...params, messages }, requestOptions) : await claude.messages.create({ ...params, messages });
+    const text = message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+    fullText += text;
+    usage = addTokenUsage(usage, {
+      inputTokens: message.usage?.input_tokens ?? 0,
+      outputTokens: message.usage?.output_tokens ?? 0
+    });
+    if (message.stop_reason !== "max_tokens") {
+      return { text: fullText, usage };
+    }
+  }
+  throw new Error(`Claude response still hit max_tokens after ${maxContinuations} continuation attempts \u2014 refusing to return truncated content.`);
+}
+
+// ../../modules/core/dist/modelRegistry.js
+var MODEL_REGISTRY = {
+  fast: {
+    description: "Quick, cheap work where depth matters least.",
+    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5" }]
+  },
+  balanced: {
+    description: "The everyday tier: chat, log entries, release notes, the daily digest. Frequent enough that cost matters.",
+    models: [{ id: "claude-sonnet-5", label: "Sonnet 5" }]
+  },
+  capable: {
+    description: "Deeper reasoning for infrequent, high-value work where getting it right outweighs the cost.",
+    models: [{ id: "claude-opus-5", label: "Opus 5" }]
+  },
+  max: {
+    description: "Maximum depth, for long-running agentic work. Opt-in \u2014 the most expensive tier.",
+    models: [{ id: "claude-fable-5", label: "Fable 5" }]
+  }
+};
+function defaultModelFor(tier) {
+  const [current] = MODEL_REGISTRY[tier].models;
+  if (!current) {
+    throw new Error(`Model tier "${tier}" has no models registered`);
+  }
+  return current.id;
+}
+
+// ../../modules/devlore/dist/ciUsage.js
+var EMPTY_PROJECT_USAGE = {
+  draftLogEntry: ZERO_USAGE,
+  consolidateRelease: ZERO_USAGE,
+  syncUserManual: ZERO_USAGE,
+  rollover: ZERO_ROLLOVER_USAGE
+};
+function usagePath(projectName) {
+  return `projects/${projectName}/usage.json`;
+}
+async function getUsageFile(octokit, { owner, repo, projectName }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({
+      owner,
+      repo,
+      path: usagePath(projectName)
+    });
+    if (Array.isArray(data) || data.type !== "file") {
+      return { usage: EMPTY_PROJECT_USAGE };
+    }
+    const parsed = JSON.parse(Buffer.from(data.content, "base64").toString("utf-8"));
+    const usage = { ...EMPTY_PROJECT_USAGE, ...parsed };
+    return { usage, sha: data.sha };
+  } catch (error) {
+    if (isNotFound(error)) {
+      return { usage: EMPTY_PROJECT_USAGE };
+    }
+    throw error;
+  }
+}
+function addUsage(current, source, delta, now = /* @__PURE__ */ new Date()) {
+  return {
+    ...current,
+    [source]: addTokenUsage(current[source], delta),
+    rollover: addRolloverUsage(current.rollover, delta, now)
+  };
+}
+async function recordUsage(octokit, params, source, delta, now = /* @__PURE__ */ new Date()) {
+  const { owner, repo, projectName, branch } = params;
+  await retryOnConflict(async () => {
+    const { usage: current, sha } = await getUsageFile(octokit, { owner, repo, projectName });
+    const updated = addUsage(current, source, delta, now);
+    await octokit.rest.repos.createOrUpdateFileContents({
+      owner,
+      repo,
+      path: usagePath(projectName),
+      message: `Record ${source} token usage: ${projectName}`,
+      content: Buffer.from(JSON.stringify(updated, null, 2), "utf-8").toString("base64"),
+      branch,
+      sha
+    });
+  });
+}
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/masterDocs.js
+function masterDocsPath(projectName) {
+  return `projects/${projectName}/master/README.md`;
+}
+async function getMasterDocs(octokit, params) {
+  return (await getMasterDocsFile(octokit, params)).content;
+}
+async function getMasterDocsSha(octokit, params) {
+  return (await getMasterDocsFile(octokit, params)).sha;
+}
+async function getMasterDocsFile(octokit, { owner, repo, projectName }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({
+      owner,
+      repo,
+      path: masterDocsPath(projectName)
+    });
+    if (Array.isArray(data) || data.type !== "file") {
+      return { content: "" };
+    }
+    return { content: Buffer.from(data.content, "base64").toString("utf-8"), sha: data.sha };
+  } catch (error) {
+    if (isNotFound2(error)) {
+      return { content: "" };
+    }
+    throw error;
+  }
+}
+function isNotFound2(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/prompt.js
+function buildConsolidationPrompt(input) {
+  const entriesText = input.logEntries.map((entry) => `--- ${entry.path} ---
+${entry.content}`).join("\n\n");
+  return [
+    `Project: ${input.projectName}`,
+    `Release: ${input.tag}`,
+    `Previous release: ${input.previousTag ?? "(none \u2014 this is the first release)"}`,
+    `Date: ${input.date}`,
+    "",
+    "Current master docs (may be empty if none exist yet):",
+    input.masterDocs || "(none yet)",
+    "",
+    "Log entries since the previous release:",
+    entriesText || "(none)",
+    "",
+    `Draft the updated master docs for ${input.projectName} as of ${input.tag}, folding in what changed across the log entries above into the current master docs. This is the official record, reviewed by a human before merging, so write it as durable reference documentation, not a changelog.`
+  ].join("\n");
+}
+
+// ../../modules/devlore/dist/logEntries.js
+function logEntriesDir(projectName) {
+  return `projects/${projectName}/log`;
+}
+async function listLogEntries(octokit, { owner, repo, projectName }) {
+  const dir = logEntriesDir(projectName);
+  let files;
+  try {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path: dir });
+    if (!Array.isArray(data)) {
+      return [];
+    }
+    files = data;
+  } catch (error) {
+    if (isNotFound3(error)) {
+      return [];
+    }
+    throw error;
+  }
+  const entries = await Promise.all(files.filter((file) => file.type === "file").map(async (file) => {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path: file.path });
+    if (Array.isArray(data) || data.type !== "file") {
+      return null;
+    }
+    return { path: file.path, content: Buffer.from(data.content, "base64").toString("utf-8") };
+  }));
+  return entries.filter((entry) => entry !== null).sort((a, b) => a.path.localeCompare(b.path));
+}
+function isNotFound3(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/releaseScope.js
+var TAG_PATTERN = /^v(\d+)\.(\d+)\.(\d+)$/;
+function parseTag(tag) {
+  const match = tag.match(TAG_PATTERN);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareTags(a, b) {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+async function findPreviousTag(octokit, { owner, repo, currentTag }) {
+  const current = parseTag(currentTag);
+  if (!current) {
+    return null;
+  }
+  const tags = await octokit.paginate(octokit.rest.repos.listTags, { owner, repo, per_page: 100 });
+  let best = null;
+  for (const tag of tags) {
+    const version = parseTag(tag.name);
+    if (!version || compareTags(version, current) >= 0) {
+      continue;
+    }
+    if (!best || compareTags(version, best.version) > 0) {
+      best = { name: tag.name, version };
+    }
+  }
+  return best?.name ?? null;
+}
+async function listCommitShasSince(octokit, { owner, repo, previousTag, currentTag }) {
+  try {
+    const { data } = await octokit.rest.repos.compareCommitsWithBasehead({
+      owner,
+      repo,
+      basehead: `${previousTag}...${currentTag}`
+    });
+    return new Set(data.commits.map((commit) => commit.sha));
+  } catch {
+    return null;
+  }
+}
+function logEntryCommitSha(entry) {
+  const filename = entry.path.split("/").pop() ?? "";
+  return filename.replace(/\.md$/, "");
+}
+async function selectLogEntriesSincePreviousRelease({ vaultOctokit, projectOctokit, vaultOwner, vaultRepoName, projectName, projectOwner, projectRepoName, tag }) {
+  const allEntries = await listLogEntries(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName });
+  const previousTag = await findPreviousTag(projectOctokit, {
+    owner: projectOwner,
+    repo: projectRepoName,
+    currentTag: tag
+  });
+  if (!previousTag) {
+    return { logEntries: allEntries, previousTag: null };
+  }
+  const commitShas = await listCommitShasSince(projectOctokit, {
+    owner: projectOwner,
+    repo: projectRepoName,
+    previousTag,
+    currentTag: tag
+  });
+  if (!commitShas) {
+    return { logEntries: allEntries, previousTag };
+  }
+  return { logEntries: allEntries.filter((entry) => commitShas.has(logEntryCommitSha(entry))), previousTag };
+}
+
+// ../../modules/devlore/dist/actions/consolidateRelease.js
+var VAULT_BASE_BRANCH = "main";
+var MODEL_TIER = "balanced";
+var MAX_TOKENS = 2e4;
+var MAX_CONTINUATIONS = 8;
+function releaseBranchName(projectName, tag) {
+  return `devkeep/${projectName}/${tag}`;
+}
+async function consolidateRelease({ projectOctokit, vaultOctokit, claude, projectOwner, projectRepoName, vaultOwner, vaultRepoName, projectName, tag }) {
+  const [{ logEntries, previousTag }, masterDocs, masterDocsSha] = await Promise.all([
+    selectLogEntriesSincePreviousRelease({
+      vaultOctokit,
+      projectOctokit,
+      vaultOwner,
+      vaultRepoName,
+      projectName,
+      projectOwner,
+      projectRepoName,
+      tag
+    }),
+    getMasterDocs(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName }),
+    getMasterDocsSha(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName })
+  ]);
+  const prompt = buildConsolidationPrompt({
+    projectName,
+    tag,
+    previousTag,
+    date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    logEntries,
+    masterDocs
+  });
+  const { text: draftedDocs, usage } = await createCompleteMessage(claude, {
+    model: defaultModelFor(MODEL_TIER),
+    max_tokens: MAX_TOKENS,
+    messages: [{ role: "user", content: prompt }]
+  }, { maxContinuations: MAX_CONTINUATIONS });
+  const branch = releaseBranchName(projectName, tag);
+  const baseRef = await vaultOctokit.rest.git.getRef({
+    owner: vaultOwner,
+    repo: vaultRepoName,
+    ref: `heads/${VAULT_BASE_BRANCH}`
+  });
+  await vaultOctokit.rest.git.createRef({
+    owner: vaultOwner,
+    repo: vaultRepoName,
+    ref: `refs/heads/${branch}`,
+    sha: baseRef.data.object.sha
+  });
+  await vaultOctokit.rest.repos.createOrUpdateFileContents({
+    owner: vaultOwner,
+    repo: vaultRepoName,
+    path: masterDocsPath(projectName),
+    message: `Consolidate release: ${projectName}@${tag}`,
+    content: Buffer.from(draftedDocs, "utf-8").toString("base64"),
+    branch,
+    sha: masterDocsSha
+  });
+  await recordUsage(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName, branch }, "consolidateRelease", usage);
+  const pr = await vaultOctokit.rest.pulls.create({
+    owner: vaultOwner,
+    repo: vaultRepoName,
+    title: `Consolidate release: ${projectName}@${tag}`,
+    head: branch,
+    base: VAULT_BASE_BRANCH,
+    body: `Drafted master doc update for \`${projectName}\` at \`${tag}\`, generated from the log entries since the last release. Review before merging \u2014 this updates the official docs.`
+  });
+  return { branch, prNumber: pr.data.number, prUrl: pr.data.html_url, usage };
+}
+
+// ../../modules/devlore/dist/bin/consolidateReleaseCli.js
+function requireEnv(env, name) {
+  const value = env[name];
+  if (!value) {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+}
+var defaultDeps = {
+  env: process.env,
+  consolidateRelease,
+  createGithubClient,
+  createClaudeClient,
+  log: console.log
+};
+async function main(deps = defaultDeps) {
+  const { env } = deps;
+  const projectName = requireEnv(env, "PROJECT_NAME");
+  const [projectOwner, projectRepoName] = requireEnv(env, "PROJECT_REPO").split("/");
+  const [vaultOwner, vaultRepoName] = requireEnv(env, "VAULT_REPO").split("/");
+  const tag = requireEnv(env, "TAG");
+  const projectOctokit = deps.createGithubClient(requireEnv(env, "GITHUB_TOKEN"));
+  const vaultOctokit = deps.createGithubClient(requireEnv(env, "DEVKEEP_GITHUB_TOKEN"));
+  const claude = deps.createClaudeClient(requireEnv(env, "ANTHROPIC_API_KEY"));
+  const result = await deps.consolidateRelease({
+    projectOctokit,
+    vaultOctokit,
+    claude,
+    projectOwner,
+    projectRepoName,
+    vaultOwner,
+    vaultRepoName,
+    projectName,
+    tag
+  });
+  deps.log(`Opened consolidation PR #${result.prNumber}: ${result.prUrl}`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+export {
+  main,
+  requireEnv
+};