@starterculture/devkeep-actions 0.2.0 → 0.3.0

package/dist/consolidate-release.js

@@ -132,6 +132,7 @@ var EMPTY_PROJECT_USAGE = {
   syncVisualizer: ZERO_USAGE,
   analyzeCodebase: ZERO_USAGE,
   syncOnboarding: ZERO_USAGE,
+  releaseNotes: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {

package/dist/draft-log-entry.js

@@ -132,6 +132,7 @@ var EMPTY_PROJECT_USAGE = {
   syncVisualizer: ZERO_USAGE,
   analyzeCodebase: ZERO_USAGE,
   syncOnboarding: ZERO_USAGE,
+  releaseNotes: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {

package/dist/draft-release-notes.js

@@ -0,0 +1,446 @@
+#!/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/prompt.js
+function buildReleaseNotesPrompt(input) {
+  return [
+    `Project: ${input.projectName}`,
+    `Release: ${input.tag}`,
+    input.previousTag ? `Previous release: ${input.previousTag}. The entries below are the work done since then.` : "This is the first release, so the entries below cover everything so far.",
+    "",
+    "Below are the decision log entries Devkeep recorded for the work in this release.",
+    "",
+    ...input.logEntries,
+    "",
+    "Write release notes for the people who use this product. Lead with what they can now do that they could not before, and what changed in behaviour they will notice. Group related changes rather than listing entries one by one.",
+    "",
+    "Plain language, not commit-history jargon: no file paths, no function names, no internal module names unless the user genuinely interacts with them by name.",
+    "",
+    'If this release contains nothing user-facing \u2014 internal refactoring, tooling, workflow changes \u2014 say exactly that in a sentence or two. Do not manufacture user-facing significance that is not there; an honest "this release contains internal changes only" is the correct output, and inventing a feature to fill the page is worse than a short note.',
+    "",
+    "Do NOT include a top-level heading \u2014 one is added automatically. Start directly with the content.",
+    "",
+    "Return the notes only \u2014 no preamble, no meta-commentary."
+  ].join("\n");
+}
+
+// ../../modules/devlore/dist/redact.js
+var REDACTED = "[REDACTED]";
+var KNOWN_SECRET_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /gh[pousr]_[A-Za-z0-9]{36,}/g,
+  /github_pat_[A-Za-z0-9_]{20,}/g,
+  /sk-ant-[A-Za-z0-9_-]{20,}/g,
+  /sk-[A-Za-z0-9]{20,}/g,
+  /AKIA[0-9A-Z]{16}/g,
+  /xox[baprs]-[A-Za-z0-9-]{10,}/g,
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g
+];
+var SECRET_KEYWORD = "(?:API[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CREDENTIAL)";
+var ASSIGNMENT_PATTERN = new RegExp(`((?:[A-Za-z0-9]+[_-])*${SECRET_KEYWORD}(?:[_-][A-Za-z0-9]+)*\\s*[:=]\\s*)(["']?)([^"'\`\\s]+)\\2`, "gi");
+function redactText(text) {
+  let result = text;
+  for (const pattern of KNOWN_SECRET_PATTERNS) {
+    result = result.replace(pattern, REDACTED);
+  }
+  result = result.replace(ASSIGNMENT_PATTERN, (_match, prefix, quote) => `${prefix}${quote}${REDACTED}${quote}`);
+  return result;
+}
+
+// ../../modules/devlore/dist/ciUsage.js
+var EMPTY_PROJECT_USAGE = {
+  draftLogEntry: ZERO_USAGE,
+  consolidateRelease: ZERO_USAGE,
+  syncUserManual: ZERO_USAGE,
+  syncTestPlan: ZERO_USAGE,
+  syncVisualizer: ZERO_USAGE,
+  analyzeCodebase: ZERO_USAGE,
+  syncOnboarding: ZERO_USAGE,
+  releaseNotes: 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/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 (isNotFound2(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 isNotFound2(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/releaseNotes.js
+function releaseNotePath(projectName, tag) {
+  return `${releaseNotesDir(projectName)}/${tag}.md`;
+}
+function releaseNotesHeading(projectName, tag) {
+  return `# ${projectName} \u2014 ${tag}`;
+}
+function releaseNotesBanner() {
+  return "> **Do not move, rename, or edit this file.** Devkeep drafted these release notes when this tag was cut.";
+}
+function releaseNotesDir(projectName) {
+  return `projects/${projectName}/releases`;
+}
+
+// ../../modules/devlore/dist/actions/draftReleaseNotes.js
+var MODEL_TIER = "balanced";
+var MAX_TOKENS = 2e4;
+var MAX_CONTINUATIONS = 8;
+var VAULT_BRANCH = "main";
+async function draftReleaseNotes({ projectOctokit, vaultOctokit, claude, projectOwner, projectRepoName, vaultOwner, vaultRepoName, projectName, tag }) {
+  const { logEntries, previousTag } = await selectLogEntriesSincePreviousRelease({
+    vaultOctokit,
+    projectOctokit,
+    vaultOwner,
+    vaultRepoName,
+    projectName,
+    projectOwner,
+    projectRepoName,
+    tag
+  });
+  const prompt = buildReleaseNotesPrompt({
+    projectName,
+    tag,
+    previousTag,
+    logEntries: logEntries.map((entry) => redactText(entry.content))
+  });
+  const { text, usage } = await createCompleteMessage(claude, { model: defaultModelFor(MODEL_TIER), max_tokens: MAX_TOKENS, messages: [{ role: "user", content: prompt }] }, { maxContinuations: MAX_CONTINUATIONS });
+  const content = `${releaseNotesBanner()}
+
+${releaseNotesHeading(projectName, tag)}
+
+${text.trim()}
+`;
+  const path = releaseNotePath(projectName, tag);
+  await vaultOctokit.rest.repos.createOrUpdateFileContents({
+    owner: vaultOwner,
+    repo: vaultRepoName,
+    path,
+    message: `Draft release notes: ${projectName} ${tag}`,
+    content: Buffer.from(content, "utf-8").toString("base64"),
+    branch: VAULT_BRANCH,
+    sha: await getExistingSha(vaultOctokit, vaultOwner, vaultRepoName, path)
+  });
+  if (usage.inputTokens > 0 || usage.outputTokens > 0) {
+    await recordUsage(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName, branch: VAULT_BRANCH }, "releaseNotes", usage);
+  }
+  return { path, previousTag, entryCount: logEntries.length, content, usage };
+}
+async function getExistingSha(octokit, owner, repo, path) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path });
+    return Array.isArray(data) || data.type !== "file" ? void 0 : data.sha;
+  } catch {
+    return void 0;
+  }
+}
+
+// ../../modules/devlore/dist/bin/draftReleaseNotesCli.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,
+  draftReleaseNotes,
+  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 vaultOctokit = deps.createGithubClient(requireEnv(env, "DEVKEEP_GITHUB_TOKEN"));
+  const projectOctokit = deps.createGithubClient(requireEnv(env, "GITHUB_TOKEN"));
+  const claude = deps.createClaudeClient(requireEnv(env, "ANTHROPIC_API_KEY"));
+  const result = await deps.draftReleaseNotes({
+    projectOctokit,
+    vaultOctokit,
+    claude,
+    projectOwner,
+    projectRepoName,
+    vaultOwner,
+    vaultRepoName,
+    projectName,
+    tag: requireEnv(env, "TAG")
+  });
+  deps.log(`Drafted release notes: ${result.path} (previous tag: ${result.previousTag ?? "none"}, ${result.entryCount} entries)`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+export {
+  main,
+  requireEnv
+};

package/dist/sync-onboarding.js

@@ -214,6 +214,7 @@ var EMPTY_PROJECT_USAGE = {
   syncVisualizer: ZERO_USAGE,
   analyzeCodebase: ZERO_USAGE,
   syncOnboarding: ZERO_USAGE,
+  releaseNotes: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starterculture/devkeep-actions",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Devkeep's GitHub Actions entrypoints, bundled for CI runners.",
   "license": "UNLICENSED",
   "type": "module",