projectbrain-Public/scripts/release-user-notes.mjs

import { spawnSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";

const outputPath = process.env.PROJECTBRAIN_USER_NOTES_OUT;
const shouldWrite = process.argv.includes("--write") || process.env.PROJECTBRAIN_USER_NOTES_WRITE === "1";

const run = (command, args) => spawnSync(command, args, {
  encoding: "utf8",
  shell: process.platform === "win32",
});

const git = (args) => {
  const result = run("git", args);
  return result.status === 0 ? result.stdout.trim() : "unknown";
};

const latestReleaseTag = () => {
  const result = run("git", ["tag", "--list", "projectbrain-rc-*", "--sort=-creatordate"]);
  return result.status === 0 ? result.stdout.trim().split(/\r?\n/).find(Boolean) ?? "untagged" : "untagged";
};

const createDefaultOutputPath = (tagName) => {
  const safeTag = tagName.replace(/[^a-zA-Z0-9._-]/g, "-");
  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
  return `checkpoints/user-release-notes/projectbrain-user-release-notes-${safeTag}-${stamp}.md`;
};

const commit = git(["rev-parse", "--short", "HEAD"]);
const tagName = process.env.PROJECTBRAIN_RELEASE_TAG ?? latestReleaseTag();
const out = outputPath || createDefaultOutputPath(tagName);

const notes = [
  "# ProjectBrain User Release Notes",
  "",
  `Generated: ${new Date().toISOString()}`,
  `Release tag: ${tagName}`,
  `Current commit: ${commit}`,
  "",
  "## What ProjectBrain Is For",
  "",
  "ProjectBrain is a project operating system for shaping, expanding and releasing software projects. It is optimized for turning ideas, existing repositories, source material and execution feedback into structured project memory, Codex-ready handoffs and release evidence.",
  "",
  "The current release is strongest as a local/operator-driven project builder. It combines project planning, repo shaping, session packaging, evidence review and release-readiness checks in one workspace.",
  "",
  "## Main User Flows",
  "",
  "### Start Or Open A Project",
  "",
  "- Use the Projects page to open an existing project.",
  "- Use Start when creating or importing a new project direction.",
  "- Existing projects remain the primary path for daily use; new-project setup is available when needed.",
  "",
  "### Shape A Repository",
  "",
  "- Use Repo Builder to inspect repository direction, gaps, state snapshots and delivery packages.",
  "- Use skill-aware handoff content to make Codex work more repeatable.",
  "- Use repo state and evidence instead of relying on memory from previous sessions.",
  "",
  "### Prepare Codex Work",
  "",
  "- Use Context Packs, Prompt Builder, Codex Handoffs and Session Packs to create a clear execution package.",
  "- Use Browser Bridge when work must be copied into ChatGPT/Codex manually without API keys.",
  "- Use Execution Feedback to bring results back into ProjectBrain as reviewable evidence.",
  "",
  "### Review And Close Work",
  "",
  "- Use Review Queue and History to inspect decisions, receipts and follow-up evidence.",
  "- Use Build Loop and Runtime Readiness to track release-relevant validation.",
  "- Use Release Center to collect proof before tagging or deploying.",
  "",
  "## Release And Operator Capabilities",
  "",
  "This release includes a complete local release-operator chain:",
  "",
  "- release smoke suite;",
  "- proof report generation;",
  "- proof freshness gate;",
  "- operator signoff file;",
  "- remote deployment proof;",
  "- release evidence dossier;",
  "- tag-ready gate;",
  "- rollback drill.",
  "",
  "Useful commands:",
  "",
  "```bash",
  "pnpm run release:bundle",
  "PROJECTBRAIN_RELEASE_DEPLOYMENT_PROOF=1 PROJECTBRAIN_RELEASE_DOSSIER=1 pnpm run release:bundle",
  "pnpm run release:tag-gate",
  "pnpm run release:rollback-drill",
  "pnpm run release:user-notes",
  "```",
  "",
  "## Deployment Notes",
  "",
  "The known live deployment target is:",
  "",
  "```text",
  "http://127.0.0.1:1209",
  "```",
  "",
  "Tower build/start commands:",
  "",
  "```bash",
  "cd /mnt/pool/appdata/brain",
  "docker compose build --no-cache frontend",
  "docker compose up -d",
  "```",
  "",
  "## What Remains Local Or Operator-Driven",
  "",
  "- Release evidence snapshots are local ignored files under `checkpoints/`.",
  "- Several release commands are intended to run from the developer/operator workstation, not from inside the Unraid container.",
  "- The rollback drill prints commands but does not execute a rollback.",
  "- Tagging remains an explicit operator action.",
  "",
  "## Known Boundaries",
  "",
  "- This release does not claim full multi-user auth.",
  "- This release does not replace all local/mock project surfaces with database-backed behavior.",
  "- This release does not automate AI calls or require API keys.",
  "- This release does not commit generated release evidence artifacts.",
  "",
  "## Recommended First Use",
  "",
  "1. Open an existing project from Projects.",
  "2. Review Workspace and Repo Builder for current direction.",
  "3. Generate or inspect a Session Pack before asking Codex to make changes.",
  "4. Capture execution feedback after a coding session.",
  "5. Use Release Center and Runtime Readiness before tagging.",
  "",
  "## Support Checklist",
  "",
  "When something looks wrong, collect:",
  "",
  "- current URL;",
  "- project id;",
  "- browser console error if present;",
  "- latest `pnpm run release:deployment-proof` output;",
  "- latest `pnpm run release:rollback-drill` output if deployment state is involved.",
].join("\n");

console.log(notes);

if (shouldWrite) {
  fs.mkdirSync(path.dirname(out), { recursive: true });
  fs.writeFileSync(out, `${notes}\n`, "utf8");
  console.log(`\nUser release notes written to ${out}`);
}