docs: add agent-safe release instructions

Author: justin-schroeder

AGENTS.md

@@ -0,0 +1,64 @@
+# Arrow Monorepo — Agent Guide
+
+Use this file for repo-wide automation and release tasks. Package-specific docs guidance still lives in `docs/AGENTS.md`.
+
+## Release automation
+
+The release entrypoint is:
+
+```sh
+pnpm run release
+```
+
+It supports both interactive and non-interactive usage.
+
+### Interactive
+
+- `pnpm run release`
+- `pnpm run release:next`
+- `pnpm run release:dev`
+
+### Non-interactive
+
+Use these forms for agent automation:
+
+```sh
+pnpm run release -- --tag next --bump patch --yes
+pnpm run release -- --tag dev --bump patch --yes
+pnpm run release -- --tag latest --bump patch --yes
+```
+
+Rules:
+
+- `latest` is only allowed from `main`
+- `next` and `dev` can be created from non-main branches
+- `latest` updates package versions in git, commits, tags, and pushes
+- `next` and `dev` create and push only a git tag; the workflow sets publish versions from the tag at release time
+
+Tag formats:
+
+- `vX.Y.Z` -> npm `latest`
+- `vX.Y.Z-next.<hash>` -> npm `next`
+- `vX.Y.Z-dev.<hash>` -> npm `dev`
+
+## Trusted publishing
+
+Publishing is handled by `.github/workflows/publish.yml`.
+
+- It uses GitHub OIDC trusted publishing
+- It installs `npm@latest`
+- It does not use an npm token
+- It blocks plain `vX.Y.Z` releases unless the tagged commit is on `main`
+
+## Public package set
+
+The automated release flow syncs and publishes:
+
+- `@arrow-js/core`
+- `@arrow-js/framework`
+- `@arrow-js/highlight`
+- `@arrow-js/hydrate`
+- `@arrow-js/ssr`
+- `@arrow-js/vite-plugin-arrow`
+- `@arrow-js/skill`
+- `create-arrow-js`

scripts/release.mjs

@@ -35,25 +35,29 @@ if (args[0] === 'sync') {
 
 await runInteractiveRelease({
   requestedTag: readFlagValue(args, '--tag'),
+  requestedBump: readFlagValue(args, '--bump'),
   dryRun: args.includes('--dry-run'),
+  skipConfirm: args.includes('--yes'),
 })
 
-async function runInteractiveRelease({ requestedTag, dryRun }) {
+async function runInteractiveRelease({ requestedTag, requestedBump, dryRun, skipConfirm }) {
   if (!isWorkingDirectoryClean()) {
     fail('Working directory is not clean. Commit or stash changes first.')
   }
 
   const branch = exec('git branch --show-current')
   const stableVersion = getStableVersion(readJson(rootPackagePath).version || readPackageVersion('packages/core'))
   const releaseTag = await resolveReleaseTag(branch, requestedTag)
-  const bumpType = await promptChoice(
-    'Select version bump type:',
-    [
-      { key: '1', value: 'patch', label: `patch (${stableVersion} -> ${bumpVersion(stableVersion, 'patch')})` },
-      { key: '2', value: 'minor', label: `minor (${stableVersion} -> ${bumpVersion(stableVersion, 'minor')})` },
-      { key: '3', value: 'major', label: `major (${stableVersion} -> ${bumpVersion(stableVersion, 'major')})` },
-    ]
-  )
+  const bumpType = requestedBump
+    ? validateBumpType(requestedBump)
+    : await promptChoice(
+        'Select version bump type:',
+        [
+          { key: '1', value: 'patch', label: `patch (${stableVersion} -> ${bumpVersion(stableVersion, 'patch')})` },
+          { key: '2', value: 'minor', label: `minor (${stableVersion} -> ${bumpVersion(stableVersion, 'minor')})` },
+          { key: '3', value: 'major', label: `major (${stableVersion} -> ${bumpVersion(stableVersion, 'major')})` },
+        ]
+      )
   const nextStable = bumpVersion(stableVersion, bumpType)
   const commitHash = exec('git rev-parse --short=7 HEAD')
   const version = releaseTag === 'latest'
@@ -72,7 +76,9 @@ async function runInteractiveRelease({ requestedTag, dryRun }) {
     ].join('\n')
   )
 
-  const confirmed = await promptConfirm(dryRun ? 'Continue with dry run?' : 'Continue with release?')
+  const confirmed = skipConfirm
+    ? true
+    : await promptConfirm(dryRun ? 'Continue with dry run?' : 'Continue with release?')
   if (!confirmed) {
     process.stdout.write('Release cancelled.\n')
     process.exit(0)
@@ -150,6 +156,14 @@ function validateReleaseTag(branch, requestedTag) {
   }
 }
 
+function validateBumpType(value) {
+  if (!['patch', 'minor', 'major'].includes(value)) {
+    fail(`Unknown bump type "${value}". Use patch, minor, or major.`)
+  }
+
+  return value
+}
+
 function getStableVersion(version) {
   return version.split('-')[0]
 }