@appsforgood/next-supabase-kit 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.0
+
+- Make GitHub Actions opt-in for fresh installs while preserving local verification gates and existing downstream workflows.
+
 ## 0.2.1
 
 - Rewrite the public README with verified setup commands and task-oriented examples for audits, council sessions, UI review, upgrades, and optional runtime orchestration.

package/DOGFOOD.md

@@ -185,3 +185,17 @@ Scope: README/docs discoverability + three new Antigravity adapters
 | Roster | `testing` and `code-review` workflows; planning triggers for spec keywords |
 | Historical scope | `/build`, `/webperf`, `/code-simplify`, and `/build auto` were deferred in this 0.1.7 review; the later runtime ships bounded roster workflows rather than cloning those command semantics |
 | Verification | `npm test`, `agent-kit adapter validate antigravity` after build |
+
+## 2026-07-11 - README Examples Release 0.2.1
+
+Date: 2026-07-11
+Scope: publish the verified README rewrite through npm Trusted Publishing and confirm the public artifacts.
+
+| Evidence | Result |
+| --- | --- |
+| Local release gate | `npm run release:check` passed with 200 tests, coverage gates, package/adapters/examples/install/Studio/setup/audit checks, zero dependency vulnerabilities, SBOM validation, and package dry runs. |
+| Root package | `@appsforgood/next-supabase-kit@0.2.1` is public and the `latest` dist-tag resolves to `0.2.1`. |
+| Published README | npm returns the rewritten quick start, audit, council-session, frontend-review, update, and optional-runtime examples for `0.2.1`. |
+| Runtime package | `@appsforgood/agent-kit-runtime` remains at `0.1.3`; the release workflow correctly skipped its unchanged package. |
+| GitHub release | [`v0.2.1`](https://github.com/lukey662/agentsandskills/releases/tag/v0.2.1) was created only after public-registry verification. |
+| Supply chain | Trusted Publishing used GitHub Actions OIDC and generated the root-package SBOM attestation before publication. |

package/README.md

@@ -106,6 +106,14 @@ npx agent-kit context init
 npx agent-kit context ask
 ```
 
+GitHub Actions is off by default. Opt in to the advisory audit workflow only when the repository has working Actions entitlement:
+
+```bash
+npx agent-kit init --github-actions
+```
+
+The workflow runs manually by default. Set the repository variable `AGENT_KIT_ACTIONS_ENABLED=true` to enable its push and pull-request jobs. Do not make the check required until the repository can reliably start Actions jobs.
+
 ### Resume project onboarding
 
 ```bash
@@ -156,7 +164,7 @@ npx agent-kit audit --schema-version 2 --format json
 npx agent-kit audit --schema-version 2 --format sarif > agent-kit.sarif
 ```
 
-### Fail CI below the required evidence level
+### Fail a local or explicitly enabled CI gate below the required evidence level
 
 ```bash
 npx agent-kit audit --min-readiness baseline-setup
@@ -181,22 +189,21 @@ on:
 
 jobs:
   audit:
+    if: ${{ github.event_name == 'workflow_dispatch' || vars.AGENT_KIT_ACTIONS_ENABLED == 'true' }}
     runs-on: ubuntu-latest
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
           node-version: 24
-          cache: npm
-      - run: npm ci
-      - run: npx agent-kit audit --min-readiness baseline-setup
+      - run: npx --yes @appsforgood/next-supabase-kit@0.3.0 audit --min-readiness baseline-setup
 ```
 
-The installed template at `.github/workflows/agent-kit-audit.yml` is the maintained starting point.
+Run `agent-kit init --github-actions` to install the maintained `.github/workflows/agent-kit-audit.yml` template. Fresh installs do not create an active hosted workflow. Account billing, spending-limit, or Actions-startup failures are external infrastructure failures; they do not replace required local test and audit evidence and do not block commit/push or normal phase progression. A project may separately make hosted checks required only after verifying Actions entitlement and branch protection.
 
 ## Common Delivery Workflows
 

package/REPOSITORY_SETTINGS.md

@@ -17,13 +17,15 @@ Protect `main` with:
 - Do not allow deletions.
 - Restrict bypasses to maintainers only.
 
-Required status checks:
+Optional status checks, only after GitHub Actions entitlement is confirmed and the project deliberately chooses hosted CI as required:
 
 - `Verify package`
 - `Review dependency changes`
 - `Analyze JavaScript and TypeScript`
 - `Scorecard`
 
+With the default `githubActions.mode: "off"`, configure no required hosted status checks. GitHub billing, spending-limit, or pre-execution failures cannot be recovered inside workflow YAML and must not block commit/push or ordinary phase progression. Preserve equivalent local test, audit, dependency, and security evidence in the council session.
+
 ## Release Environment
 
 Create environment `npm-publish` with:

package/SUPPLY_CHAIN.md

@@ -37,8 +37,9 @@ The release workflow and `npm run publish:verify` both use `scripts/post-publish
 
 ## Repository Automation
 
-- CI verifies package behavior on push and pull request.
-- Dependency Review blocks pull requests that introduce moderate or worse known vulnerabilities.
+- Local `npm run release:check` is the default package verification and supply-chain gate.
+- Hosted CI may mirror package verification on push and pull request when Actions entitlement is deliberately enabled.
+- Dependency Review can block pull requests that introduce moderate or worse known vulnerabilities when hosted Actions is available; otherwise review `npm audit` and lockfile changes locally.
 - Dependabot proposes npm and GitHub Actions updates; workflow actions remain pinned to immutable commit SHAs with reviewed version comments.
 - CodeQL scans JavaScript/TypeScript code.
 - OpenSSF Scorecard publishes repository security posture as code-scanning evidence.

package/dist/index.js

@@ -182,11 +182,14 @@ import { join as join14, normalize } from "path";
 
 // src/config/defaults.ts
 var PACKAGE_NAME = "@appsforgood/next-supabase-kit";
-var PACKAGE_VERSION = "0.2.1";
+var PACKAGE_VERSION = "0.3.0";
 var DEFAULT_CONFIG = {
   stack: "next-supabase",
   projectType: "saas",
   docsMode: "advisory",
+  githubActions: {
+    mode: "off"
+  },
   agentCouncil: {
     required: true,
     rosterPath: ".agent-kit/agent-roster.json",
@@ -1726,7 +1729,7 @@ function ideSurfaceToActivateTarget(ideSurface) {
 // src/install/managed-assets.ts
 import { readFileSync as readFileSync8 } from "fs";
 import { join as join10 } from "path";
-function listManagedAssets(packageRoot, stack) {
+function listManagedAssets(packageRoot, stack, options = {}) {
   const assets = [];
   const templateRoot = join10(packageRoot, "templates", stack);
   for (const target of ROOT_DOCS) {
@@ -1741,8 +1744,10 @@ function listManagedAssets(packageRoot, stack) {
     { target: DEFAULT_ORCHESTRATOR_TARGET, sourcePath: join10(packageRoot, DEFAULT_ORCHESTRATOR_SOURCE), category: "orchestrator" },
     { target: DEFAULT_RUNTIME_IGNORE_TARGET, sourcePath: join10(packageRoot, DEFAULT_RUNTIME_IGNORE_SOURCE), category: "orchestrator" }
   );
-  for (const template of CI_TEMPLATE_FILES) {
-    assets.push({ target: template.target, sourcePath: join10(packageRoot, template.source), category: "ci" });
+  if (options.includeCi) {
+    for (const template of CI_TEMPLATE_FILES) {
+      assets.push({ target: template.target, sourcePath: join10(packageRoot, template.source), category: "ci" });
+    }
   }
   for (const folder of LIBRARY_FOLDERS) {
     for (const relativePath of listFilesRecursive(join10(packageRoot, folder))) {
@@ -1768,7 +1773,9 @@ function initProject(options) {
   const stack = options.stack ?? DEFAULT_CONFIG.stack;
   const packageRoot = findPackageRoot();
   const templateRoot = join11(packageRoot, "templates", stack);
-  const managedAssets = listManagedAssets(packageRoot, stack);
+  const existingGithubActionsMode = readGithubActionsMode(cwd);
+  const githubActionsMode = options.githubActions || existingGithubActionsMode === "advisory" ? "advisory" : "off";
+  const managedAssets = listManagedAssets(packageRoot, stack, { includeCi: githubActionsMode !== "off" });
   if (!existsSync10(templateRoot)) {
     throw new Error(`Unsupported stack profile: ${stack}`);
   }
@@ -1863,20 +1870,26 @@ function initProject(options) {
   };
   writeText(join11(cwd, ".agent-kit", "manifest.json"), `${JSON.stringify(manifest, null, 2)}
 `);
-  writeText(join11(cwd, ".agent-kit", "config.json"), `${JSON.stringify(DEFAULT_CONFIG, null, 2)}
+  const config = {
+    ...DEFAULT_CONFIG,
+    githubActions: { mode: githubActionsMode }
+  };
+  writeText(join11(cwd, ".agent-kit", "config.json"), `${JSON.stringify(config, null, 2)}
 `);
   const overridesPath = join11(cwd, ".agent-kit", "overrides.json");
   if (!existsSync10(overridesPath)) writeText(overridesPath, `${JSON.stringify({ templates: {} }, null, 2)}
 `);
-  for (const template of CI_TEMPLATE_FILES) {
-    const ciCopy = copyTextWithConflict(join11(packageRoot, template.source), cwd, template.target, {
-      force: Boolean(options.force),
-      conflictRoot: join11(cwd, ".agent-kit", "conflicts")
-    });
-    if (ciCopy.action === "created") result.copied.push(ciCopy.target);
-    if (ciCopy.action === "unchanged") result.unchanged.push(ciCopy.target);
-    if (ciCopy.action === "overwritten") result.overwritten.push(ciCopy.target);
-    if (ciCopy.action === "conflict") result.conflicts.push(`${ciCopy.target} -> ${ciCopy.conflictPath}`);
+  if (githubActionsMode !== "off") {
+    for (const template of CI_TEMPLATE_FILES) {
+      const ciCopy = copyTextWithConflict(join11(packageRoot, template.source), cwd, template.target, {
+        force: Boolean(options.force),
+        conflictRoot: join11(cwd, ".agent-kit", "conflicts")
+      });
+      if (ciCopy.action === "created") result.copied.push(ciCopy.target);
+      if (ciCopy.action === "unchanged") result.unchanged.push(ciCopy.target);
+      if (ciCopy.action === "overwritten") result.overwritten.push(ciCopy.target);
+      if (ciCopy.action === "conflict") result.conflicts.push(`${ciCopy.target} -> ${ciCopy.conflictPath}`);
+    }
   }
   const context2 = initProjectContext(cwd);
   result.contextPath = context2.contextPath;
@@ -1899,6 +1912,23 @@ function readManifest(cwd) {
   if (!existsSync10(manifestPath)) return null;
   return JSON.parse(readFileSync9(manifestPath, "utf8"));
 }
+function readGithubActionsMode(cwd) {
+  const configPath = join11(cwd, ".agent-kit", "config.json");
+  if (!existsSync10(configPath)) {
+    const manifest = readManifest(cwd);
+    return manifest?.assetHashes?.[".github/workflows/agent-kit-audit.yml"] ? "advisory" : "off";
+  }
+  try {
+    const config = JSON.parse(readFileSync9(configPath, "utf8"));
+    const mode = config.githubActions?.mode;
+    if (mode === "off" || mode === "advisory") return mode;
+    const manifest = readManifest(cwd);
+    return manifest?.assetHashes?.[".github/workflows/agent-kit-audit.yml"] ? "advisory" : "off";
+  } catch {
+    const manifest = readManifest(cwd);
+    return manifest?.assetHashes?.[".github/workflows/agent-kit-audit.yml"] ? "advisory" : "off";
+  }
+}
 
 // src/install/audit-rules/project-reality.ts
 import { execFileSync } from "child_process";
@@ -4237,10 +4267,11 @@ function diffStatus(plan) {
   if (plan.action === "unchanged") return "unchanged";
   return "changed";
 }
-function diffProject(cwd, stack = "next-supabase") {
+function diffProject(cwd, stack = "next-supabase", options = {}) {
   const packageRoot = findPackageRoot();
   const manifest = readManifest(cwd);
-  const assets = listManagedAssets(packageRoot, stack);
+  const includeCi = options.githubActions ?? readGithubActionsMode(cwd) !== "off";
+  const assets = listManagedAssets(packageRoot, stack, { includeCi });
   const plans = assets.map((asset) => ({
     asset,
     plan: planFileUpdate({
@@ -4325,7 +4356,7 @@ function updateProject(options) {
   const stack = manifest.stack ?? "next-supabase";
   const templateRoot = join17(packageRoot, "templates", stack);
   if (!existsSync17(templateRoot)) throw new Error(`Unsupported stack profile in manifest: ${stack}`);
-  const assets = listManagedAssets(packageRoot, stack);
+  const assets = listManagedAssets(packageRoot, stack, { includeCi: readGithubActionsMode(cwd) !== "off" });
   const plans = assets.map(
     (asset) => planFileUpdate({
       target: asset.target,
@@ -7891,10 +7922,10 @@ async function runSetupServer(options) {
     process.once("SIGTERM", shutdown);
   });
 }
-program.command("init").description("Install agent-kit docs and library files into a project.").option("--stack <stack>", "Stack profile to install.", "next-supabase").option("--force", "Overwrite existing docs instead of writing conflicts.").option("--activate <targets...>", "Promote IDE/runtime adapters: cursor, claude, codex, copilot, antigravity, or all.").option("--guided", "Also create local project context files (interactive on a terminal, scan-based otherwise).").option("--dry-run", "Preview what init would create or conflict on without writing files.").option("--json", "Print machine-readable JSON output.").option("--setup", "Start the setup wizard after install.").option("--no-setup", "Skip the post-install setup wizard prompt.").option("--open", "Open the setup wizard in your default browser.").action(async (options) => {
+program.command("init").description("Install agent-kit docs and library files into a project.").option("--stack <stack>", "Stack profile to install.", "next-supabase").option("--force", "Overwrite existing docs instead of writing conflicts.").option("--activate <targets...>", "Promote IDE/runtime adapters: cursor, claude, codex, copilot, antigravity, or all.").option("--github-actions", "Install the optional advisory GitHub Actions audit workflow (off by default).").option("--guided", "Also create local project context files (interactive on a terminal, scan-based otherwise).").option("--dry-run", "Preview what init would create or conflict on without writing files.").option("--json", "Print machine-readable JSON output.").option("--setup", "Start the setup wizard after install.").option("--no-setup", "Skip the post-install setup wizard prompt.").option("--open", "Open the setup wizard in your default browser.").action(async (options) => {
   const cwd = process.cwd();
   if (options.dryRun) {
-    const preview = diffProject(cwd, options.stack);
+    const preview = diffProject(cwd, options.stack, options.githubActions ? { githubActions: true } : {});
     if (options.json) {
       printJson({ dryRun: true, preview: preview.preview, missing: preview.missing, changed: preview.changed, unchanged: preview.unchanged });
       return;
@@ -7911,6 +7942,7 @@ program.command("init").description("Install agent-kit docs and library files in
     cwd,
     stack: options.stack,
     force: Boolean(options.force),
+    githubActions: Boolean(options.githubActions),
     ...options.activate ? { activate: options.activate } : {}
   });
   const context2 = options.guided ? initProjectContext(cwd) : null;