@starterculture/devkeep-actions 0.1.0 → 0.2.0

package/dist/consolidate-release.js

@@ -128,6 +128,10 @@ 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,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {

package/dist/draft-log-entry.js

@@ -128,6 +128,10 @@ 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,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {

package/dist/sync-onboarding.js

@@ -0,0 +1,453 @@
+#!/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/decisionEntries.js
+function decisionEntriesDir(projectName) {
+  return `projects/${projectName}/decisions`;
+}
+async function listDecisionEntries(octokit, { owner, repo, projectName }) {
+  const dir = decisionEntriesDir(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 (isNotFound(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 isNotFound(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/prompt.js
+function buildOnboardingGuidePrompt(input) {
+  return [
+    `Project: ${input.projectName}`,
+    "",
+    'Write a "start here" guide for a developer joining this project. Not an end-user manual, and not a changelog \u2014 an orientation for someone about to read and change the code.',
+    "",
+    input.currentState ? `--- Current state ---
+${input.currentState}` : "",
+    input.masterDocs ? `--- Master docs ---
+${input.masterDocs}` : "",
+    input.decisions.length > 0 ? `--- Decisions ---
+${input.decisions.join("\n\n")}` : "",
+    "",
+    "Cover, in whatever order serves a newcomer best:",
+    "",
+    "- Where the important logic lives, and what to read first.",
+    "- Why the significant past decisions were made \u2014 a newcomer who does not know the reasoning will undo it.",
+    "- Common gotchas: the things that look wrong but are deliberate, and the mistakes this codebase has actually made before.",
+    "- How to get from a clean checkout to a working change.",
+    "",
+    "Draw only on what the documents above actually say. Where they do not cover something a newcomer would need, say so plainly rather than inventing a plausible answer \u2014 this guide is read by someone with no way to tell the difference.",
+    "",
+    "Return the guide only \u2014 no preamble, no meta-commentary."
+  ].filter((line) => line !== "").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,
+  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 (isNotFound2(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 isNotFound2(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 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 (isNotFound3(error)) {
+      return { content: "" };
+    }
+    throw error;
+  }
+}
+function isNotFound3(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/codebaseSnapshot.js
+function currentStatePath(projectName) {
+  return `projects/${projectName}/current-state.md`;
+}
+
+// ../../modules/devlore/dist/onboardingDoc.js
+var ONBOARDING_PATH = "docs/ONBOARDING.md";
+var BANNER_BLOCKQUOTE_PATTERN = /^> \*\*Do not move.*$\n?/m;
+function onboardingBanner() {
+  return "> **Do not move, rename, or edit this file.** Devkeep generates and maintains this onboarding guide automatically at each release \u2014 manual edits will be overwritten the next time a release is tagged.";
+}
+function stripOnboardingMeta(content) {
+  return content.replace(BANNER_BLOCKQUOTE_PATTERN, "").trim();
+}
+async function getExistingOnboarding(octokit, { owner, repo }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path: ONBOARDING_PATH });
+    if (Array.isArray(data) || data.type !== "file") {
+      return null;
+    }
+    return { content: Buffer.from(data.content, "base64").toString("utf-8"), sha: data.sha };
+  } catch (error) {
+    if (isNotFound4(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+function onboardingVaultPath(projectName) {
+  return `projects/${projectName}/onboarding.md`;
+}
+async function getVaultOnboarding(octokit, { owner, repo, projectName }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({
+      owner,
+      repo,
+      path: onboardingVaultPath(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 (isNotFound4(error)) {
+      return { content: "" };
+    }
+    throw error;
+  }
+}
+function isNotFound4(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/actions/syncOnboarding.js
+var MODEL_TIER = "balanced";
+var MAX_TOKENS = 2e4;
+var MAX_CONTINUATIONS = 8;
+var VAULT_BRANCH = "main";
+async function readVaultFile(octokit, owner, repo, path) {
+  const { data } = await octokit.rest.repos.getContent({ owner, repo, path }).catch(() => ({ data: null }));
+  return data && !Array.isArray(data) && data.type === "file" ? Buffer.from(data.content, "base64").toString("utf-8") : "";
+}
+async function syncOnboarding({ projectOctokit, vaultOctokit, claude, projectOwner, projectRepoName, vaultOwner, vaultRepoName, projectName }) {
+  const [currentState, masterDocs, entries] = await Promise.all([
+    readVaultFile(vaultOctokit, vaultOwner, vaultRepoName, currentStatePath(projectName)),
+    getMasterDocs(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName }).catch(() => ""),
+    listDecisionEntries(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName }).catch(() => [])
+  ]);
+  const prompt = buildOnboardingGuidePrompt({
+    projectName,
+    currentState: redactText(currentState),
+    masterDocs: redactText(masterDocs),
+    decisions: entries.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 = `${onboardingBanner()}
+
+${text.trim()}
+`;
+  const existing = await getExistingOnboarding(projectOctokit, { owner: projectOwner, repo: projectRepoName });
+  await projectOctokit.rest.repos.createOrUpdateFileContents({
+    owner: projectOwner,
+    repo: projectRepoName,
+    path: ONBOARDING_PATH,
+    message: existing ? "Update onboarding guide" : "Add onboarding guide",
+    content: Buffer.from(content, "utf-8").toString("base64"),
+    sha: existing?.sha
+  });
+  const vaultPath = onboardingVaultPath(projectName);
+  const mirrored = stripOnboardingMeta(content);
+  const existingVault = await getVaultOnboarding(vaultOctokit, {
+    owner: vaultOwner,
+    repo: vaultRepoName,
+    projectName
+  });
+  if (existingVault.content !== mirrored) {
+    await vaultOctokit.rest.repos.createOrUpdateFileContents({
+      owner: vaultOwner,
+      repo: vaultRepoName,
+      path: vaultPath,
+      message: `Mirror onboarding guide: ${projectName}`,
+      content: Buffer.from(mirrored, "utf-8").toString("base64"),
+      branch: VAULT_BRANCH,
+      sha: existingVault.sha
+    });
+  }
+  if (usage.inputTokens > 0 || usage.outputTokens > 0) {
+    await recordUsage(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName, branch: VAULT_BRANCH }, "syncOnboarding", usage);
+  }
+  return { path: ONBOARDING_PATH, vaultPath, content, usage };
+}
+
+// ../../modules/devlore/dist/bin/syncOnboardingCli.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,
+  syncOnboarding,
+  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 octokit = deps.createGithubClient(requireEnv(env, "DEVKEEP_GITHUB_TOKEN"));
+  const claude = deps.createClaudeClient(requireEnv(env, "ANTHROPIC_API_KEY"));
+  const result = await deps.syncOnboarding({
+    projectOctokit: octokit,
+    vaultOctokit: octokit,
+    claude,
+    projectOwner,
+    projectRepoName,
+    vaultOwner,
+    vaultRepoName,
+    projectName
+  });
+  deps.log(`Synced onboarding guide: ${result.path} (mirrored to ${result.vaultPath})`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+export {
+  main,
+  requireEnv
+};

package/package.json

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