@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/scripts/version/version-remote.ts

@@ -1,6 +1,7 @@
-import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { error_text } from '#scripts/lib/error-message'
-import { safe_json_parse } from './parse-json'
+import { json_value } from '#scripts/lib/json-value'
+import { npm_registry } from './npm-registry'
 import { release_age } from './release-age'
 
 // Enough history to reach past a quarantine window into the newest release that has aged out of it.
@@ -22,14 +23,18 @@ function require_endpoint(versions_endpoint: string | undefined, package_name: s
 	)
 }
 
-// Fetch the latest published version from a GitHub Packages versions endpoint. The endpoint is
-// supplied per package (e.g. `/users/joshuafolkken/packages/npm/kit/versions?per_page=1`) so the
-// same fetcher serves kit, jgame, and app-kit. Guards an undefined/empty endpoint and wraps
-// `gh api` failures with an actionable message instead of a raw ExecaSyncError stack. The detail is
-// the shared layer's failure text: gh's own stderr (e.g. "gh: Not Found (HTTP 404)") when it wrote
-// one, execa's message otherwise, followed by any JSON error body gh wrote to stdout.
+// Fetch the latest published version: public npm's `latest` dist-tag first, which needs no
+// credentials (joshuafolkken/kit#2882), then the GitHub Packages versions endpoint for a package
+// public npm does not answer for. The endpoint is supplied per package (e.g.
+// `/users/joshuafolkken/packages/npm/kit/versions?per_page=1`) so the same fetcher serves kit, jgame,
+// and app-kit. Guards an undefined/empty endpoint and wraps `gh api` failures with an actionable
+// message instead of a raw ExecaSyncError stack. The detail is the shared layer's failure text: gh's
+// own stderr (e.g. "gh: Not Found (HTTP 404)") when it wrote one, execa's message otherwise, followed
+// by any JSON error body gh wrote to stdout.
 function fetch_latest_version(versions_endpoint: string | undefined, package_name: string): string {
 	const endpoint = require_endpoint(versions_endpoint, package_name)
+	const public_latest = npm_registry.read_latest(package_name)
+	if (public_latest !== undefined) return public_latest
 
 	try {
 		return git_gh_exec.exec_gh_api_sync({ path: endpoint, jq_filter: '.[0].name' }).trim()
@@ -59,19 +64,28 @@ function with_page_size(endpoint: string, page_size: number): string {
 	return `${path_part}?${query.toString()}`
 }
 
+function read_github_release_times(versions_endpoint: string): Record<string, string> | undefined {
+	const endpoint = with_page_size(versions_endpoint, TIMES_PAGE_SIZE)
+	const stdout = git_gh_exec.read_gh_api_sync({ path: endpoint, jq_filter: TIMES_JQ })
+	if (stdout === undefined) return undefined
+	const parsed = release_age.release_times_schema.safeParse(json_value.parse_or_undefined(stdout))
+
+	return parsed.success ? parsed.data : undefined
+}
+
 // Publish timestamps for the package's recent releases, or nothing. Unlike `fetch_latest_version`
 // this never throws: the timestamps only enrich an explanation, so a package whose history cannot be
-// read keeps the report it had before (joshuafolkken/kit#808).
+// read keeps the report it had before (joshuafolkken/kit#808). Read in the same source order as
+// the latest, so the hold is explained against the registry `latest` came from.
 function fetch_release_times(
 	versions_endpoint: string | undefined,
+	package_name: string,
 ): Record<string, string> | undefined {
 	if (versions_endpoint === undefined || versions_endpoint.trim() === '') return undefined
-	const endpoint = with_page_size(versions_endpoint, TIMES_PAGE_SIZE)
-	const stdout = git_gh_exec.read_gh_api_sync({ path: endpoint, jq_filter: TIMES_JQ })
-	if (stdout === undefined) return undefined
-	const parsed = release_age.release_times_schema.safeParse(safe_json_parse(stdout))
 
-	return parsed.success ? parsed.data : undefined
+	return (
+		npm_registry.read_release_times(package_name) ?? read_github_release_times(versions_endpoint)
+	)
 }
 
 export { fetch_latest_version, fetch_release_times, with_page_size }

package/scripts/version/version-targets.ts

@@ -1,8 +1,8 @@
 import path from 'node:path'
+import { json_value } from '#scripts/lib/json-value'
 import { file_reader } from '#scripts/lib/read-file'
 import { package_version_schema, pnpm_ls_global_schema } from '#scripts/lib/schemas'
 import { execaSync } from 'execa'
-import { safe_json_parse } from './parse-json'
 
 const NODE_MODULES = 'node_modules'
 const PACKAGE_JSON = 'package.json'
@@ -15,7 +15,7 @@ function build_pnpm_ls_arguments(package_name: string): Array<string> {
 // Read the globally installed version from `pnpm ls -g --json` output. Returns undefined when
 // the package is absent or the output cannot be parsed (e.g. pnpm missing, empty stdout).
 function parse_global_version(stdout: string, package_name: string): string | undefined {
-	const parsed = pnpm_ls_global_schema.safeParse(safe_json_parse(stdout))
+	const parsed = pnpm_ls_global_schema.safeParse(json_value.parse_or_undefined(stdout))
 	if (!parsed.success) return undefined
 
 	return parsed.data[0]?.dependencies?.[package_name]?.version
@@ -25,7 +25,7 @@ function parse_global_version(stdout: string, package_name: string): string | un
 // file is missing (raw is undefined) or malformed.
 function parse_project_version(raw: string | undefined): string | undefined {
 	if (raw === undefined) return undefined
-	const parsed = package_version_schema.safeParse(safe_json_parse(raw))
+	const parsed = package_version_schema.safeParse(json_value.parse_or_undefined(raw))
 
 	return parsed.success ? parsed.data.version : undefined
 }
@@ -61,7 +61,7 @@ function read_workspace_version(cwd: string): string | undefined {
 // `📦 project version: <v>` for the end of a workflow. Both are gone (joshuafolkken/kit#1486): a
 // child no longer bumps, so the local manifest names the *previous* release rather than what the run
 // ships, and every caller now prints the count of unreleased merges instead
-// (`scripts/git/git-followup-pending.ts`). Removed rather than left unused, so nothing reaches for
+// (`scripts/followup/git-followup-pending.ts`). Removed rather than left unused, so nothing reaches for
 // the misleading reading again.
 
 const version_targets = {

package/templates/sonar-project.properties

@@ -24,7 +24,11 @@ sonar.exclusions=.claude/**,scripts/**
 # tooling. A `*-file` flag takes a path the developer typed on their own command
 # line — the same trust level as the command itself — so there is no untrusted
 # input boundary for the taint analysis to protect, exactly as with S4036.
-sonar.issue.ignore.multicriteria=e1,e2,e3,e4,e5,e6,e7,e8
+#
+# Suppress "await inside a loop" (S9382) everywhere. ESLint's `no-await-in-loop` reports the same
+# pattern in the local gate, and each intentional sequential await carries its reason on an
+# `eslint-disable-next-line` comment — which SonarJS does not read — so ESLint is the single gate.
+sonar.issue.ignore.multicriteria=e1,e2,e3,e4,e5,e6,e7,e8,e9,e10,e11,e12,e13,e14
 sonar.issue.ignore.multicriteria.e1.ruleKey=typescript:S4036
 sonar.issue.ignore.multicriteria.e1.resourceKey=scripts/**/*
 sonar.issue.ignore.multicriteria.e2.ruleKey=typescript:S4036
@@ -41,6 +45,29 @@ sonar.issue.ignore.multicriteria.e7.ruleKey=jssecurity:S8707
 sonar.issue.ignore.multicriteria.e7.resourceKey=scripts/**/*
 sonar.issue.ignore.multicriteria.e8.ruleKey=jssecurity:S8707
 sonar.issue.ignore.multicriteria.e8.resourceKey=scripts-ai/**/*
+# Suppress "async function without await" (S7503) everywhere. The shared ESLint
+# config enforces `@typescript-eslint/promise-function-async`, so a function that
+# returns a Promise must be `async` even when it has nothing to await; that is why
+# it turns `require-await` off, and S7503 is the same rule under another name —
+# the two cannot both hold.
+sonar.issue.ignore.multicriteria.e9.ruleKey=typescript:S7503
+sonar.issue.ignore.multicriteria.e9.resourceKey=**/*
+sonar.issue.ignore.multicriteria.e10.ruleKey=javascript:S7503
+sonar.issue.ignore.multicriteria.e10.resourceKey=**/*
+# Suppress "prefer Number static properties" (S7773) everywhere. It asks for
+# `Number.NaN`, while the unicorn recommended preset the shared ESLint config
+# enforces asks for the opposite (`prefer-global-number-constants`: `NaN` over
+# `Number.NaN`) — the two cannot both hold. The rest of what S7773 covers
+# (`Number.parseInt`, `Number.isNaN`, …) is already enforced by
+# `unicorn/prefer-number-properties`.
+sonar.issue.ignore.multicriteria.e11.ruleKey=typescript:S7773
+sonar.issue.ignore.multicriteria.e11.resourceKey=**/*
+sonar.issue.ignore.multicriteria.e12.ruleKey=javascript:S7773
+sonar.issue.ignore.multicriteria.e12.resourceKey=**/*
+sonar.issue.ignore.multicriteria.e13.ruleKey=typescript:S9382
+sonar.issue.ignore.multicriteria.e13.resourceKey=**/*
+sonar.issue.ignore.multicriteria.e14.ruleKey=javascript:S9382
+sonar.issue.ignore.multicriteria.e14.resourceKey=**/*
 
 # Files to exclude from the duplicate check.
 # Snapshot files (.snap) contain machine-generated repetitive patterns and are not authored code.

package/templates/workflows/dependabot-auto-merge.yml

@@ -50,8 +50,10 @@ jobs:
       #
       # Everything comes from the API, so no checkout is needed. `--paginate` is what makes the file
       # list complete rather than the first page of a large diff, and the `select` narrows it to
-      # workflows inside `--jq` rather than through `grep`: the default shell is `bash -e` without
-      # `pipefail`, so a `gh` failure inside a pipeline would be masked by grep's status, and grep
+      # workflows — and the local composite actions under `.github/actions/`, which are stamped and
+      # overwritten the same way (joshuafolkken/kit#3013) — inside `--jq` rather than through `grep`:
+      # the default shell is `bash -e` without `pipefail`, so a `gh` failure inside a pipeline would
+      # be masked by grep's status, and grep
       # itself answers 1 for "no match" and 2 for "I could not look" — two readings this step must
       # not conflate, since one of them means "merge it" (joshuafolkken/kit#844). An assignment
       # carries the command's status, and `case` has no failure mode at all.
@@ -88,7 +90,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           changed="$(gh api "repos/$REPOSITORY/pulls/$PR_NUMBER/files" --paginate \
-            --jq '.[] | select(.filename | startswith(".github/workflows/"))
+            --jq '.[] | select(.filename | startswith(".github/workflows/") or startswith(".github/actions/"))
                       | [.filename, .contents_url] | @tsv')"
 
           has_managed=false

package/templates/workflows/github-release.yml

@@ -0,0 +1,81 @@
+name: GitHub Release
+
+# Creates the GitHub Release, with notes generated from `.github/release.yml`, for each tag
+# `josh release` cuts (joshuafolkken/kit#3007). A repository with a Publish workflow gets its release
+# once that workflow has succeeded for the tag; one without it gets the release when auto-tag.yml
+# announces the tag. kit's own release is the `create-release` job of its publish.yml, which runs the
+# same `josh release:github`, so this file is distributed but never runs in kit.
+on:
+  workflow_run:
+    workflows: [Publish]
+    types: [completed]
+  repository_dispatch:
+    types: [new-tag-created]
+
+# Deliberately no `concurrency` block: a later tag waits inside `josh release:github` for the lower
+# tag's release, so serializing the runs would leave the later run holding the slot the lower one needs.
+
+jobs:
+  release:
+    # The Publish run is titled `Publish <tag>`; its head branch is not the tag when it was started by
+    # repository_dispatch, so the title is where the tag is read from.
+    if: >-
+      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success' &&
+      startsWith(github.event.workflow_run.display_title, 'Publish v')) ||
+      github.event_name == 'repository_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 65
+    permissions:
+      actions: read
+      contents: write
+      packages: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      # A repository with a Publish workflow is released from the workflow_run above, after its
+      # publication, so the tag announcement is left alone there and one tag never starts two releases.
+      - name: Select release tag
+        id: release
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          RUN_TITLE: ${{ github.event.workflow_run.display_title }}
+          RUN_WORKFLOW: ${{ github.event.workflow_run.workflow_id }}
+          DISPATCH_TAG: ${{ github.event.client_payload.tag }}
+        run: |
+          if [ "$EVENT_NAME" = workflow_run ]; then
+            echo "tag=${RUN_TITLE#Publish }" >> "$GITHUB_OUTPUT"
+            echo "workflow=$RUN_WORKFLOW" >> "$GITHUB_OUTPUT"
+          elif [ -f .github/workflows/publish.yml ]; then
+            echo "ℹ️ publish.yml releases this tag once it has published, skipping"
+          else
+            echo "tag=$DISPATCH_TAG" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Setup Node.js
+        if: steps.release.outputs.tag != ''
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+
+      - name: Configure GitHub Packages authentication for existing projects
+        if: steps.release.outputs.tag != ''
+        run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
+
+      - name: Setup pnpm and install dependencies
+        if: steps.release.outputs.tag != ''
+        uses: ./.github/actions/setup-pnpm
+        with:
+          node-auth-token: ${{ secrets.GITHUB_TOKEN }}
+          cache: 'false'
+
+      - name: Publish GitHub Release
+        if: steps.release.outputs.tag != ''
+        run: pnpm josh release:github
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ steps.release.outputs.tag }}
+          RELEASE_WORKFLOW: ${{ steps.release.outputs.workflow }}

package/prompts/collaboration-workflow/cross-repo-epic.md

@@ -1,5 +0,0 @@
-## リポジトリをまたぐ EPIC
-
-**この規則の単一ソースは `.claude/skills/epic-commands/SKILL.md` → "Epics that span repositories" である。** 子の書き方、owner の制限、自動クローズ、公開の完了を待つ依存、配布物を持たない repo、実行のディスパッチ、`owner/repo#N` での参照はすべてそこにある。
-
-経緯（公開待ちが要る理由、joshuafolkken/kit#1129）は [`docs/maintainers/epic-commands-rationale.md`](../../docs/maintainers/epic-commands-rationale.md) にある。

package/prompts/collaboration-workflow/epic-audit.md

@@ -1,5 +0,0 @@
-## `josh epic:audit` — 子 Issue 群を横断して矛盾を検出する
-
-**この規則の単一ソースは `.claude/skills/epic-commands/SKILL.md` → "`josh epic:audit <E>` — contradictions across the children" である。** 検査表、警告とエラーの区別、片方が closed の組を警告に降格する規則、孤児検索の 2 つの結果、Tier A の修正、計画時の波及先の点検はすべてそこにある。
-
-経緯（joshuafolkken/kit#858 の監査で見つかった矛盾と波及漏れ、joshuafolkken/kit#1010）は [`docs/maintainers/epic-commands-rationale.md`](../../docs/maintainers/epic-commands-rationale.md) にある。

package/prompts/collaboration-workflow/epic-bundle.md

@@ -1,5 +0,0 @@
-## 後から関連が判明した Issue を epic に束ねる
-
-**この規則の単一ソースは `.claude/skills/epic-commands/SKILL.md` → "`josh epic:bundle <N>` — does this new issue belong with one already filed?" である。** 発火点、強い信号、候補探索の範囲、決定木、所属先の記録、順序の記録、起票前の `issue:scout` はすべてそこにある。レビュー上限で切り出す後追い Issue の起票と答えへの対応は `prompts/review.md` → "Three-way disposition after the cap" が単一ソースである。
-
-経緯（joshuafolkken/kit#943 / #946 / #947 の取りこぼし、CI 待ちに起票を置く根拠の計測）は [`docs/maintainers/epic-commands-rationale.md`](../../docs/maintainers/epic-commands-rationale.md) にある。

package/scripts/init/plugin-install-hint.ts

@@ -1,47 +0,0 @@
-import { readdirSync } from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { claude_plugin_config } from './claude-plugin-config'
-
-// `josh init` / `josh sync` declare the kit plugin in the consumer's `.claude/settings.json`, but the
-// CLI does not install it from the declaration alone — a consumer runs `claude plugin install kit@kit`
-// once (joshuafolkken/kit#1930). Nothing said so at the end of init or sync, so a consumer whose
-// skills silently never loaded had no pointer to the one command that fixes it. This prints that
-// command on completion, unless the plugin already appears installed.
-
-const PLUGINS_SUBDIR = path.join('.claude', 'plugins')
-
-// Best effort: Claude Code records installed marketplaces under `~/.claude/plugins`. The kit
-// marketplace directory being present is the strongest signal available at the shell; the plugin's
-// enabled state is not readable here, so an uncertain read (no directory, no permission) counts as
-// "not installed". A hint shown once too often costs a line; one never shown costs a consumer its skills.
-function is_plugin_installed(home_directory: string = os.homedir()): boolean {
-	try {
-		return readdirSync(path.join(home_directory, PLUGINS_SUBDIR)).some(
-			(entry) =>
-				entry === claude_plugin_config.MARKETPLACE_NAME ||
-				entry.startsWith(`${claude_plugin_config.MARKETPLACE_NAME}@`),
-		)
-	} catch {
-		return false
-	}
-}
-
-function plugin_install_hint(is_installed: boolean): string | undefined {
-	if (is_installed) return undefined
-
-	return `  ℹ Skills load from the kit plugin. If they are missing, run: claude plugin install ${claude_plugin_config.PLUGIN_ID}`
-}
-
-function report_plugin_install_hint(home_directory?: string): void {
-	const hint = plugin_install_hint(is_plugin_installed(home_directory))
-	if (hint !== undefined) console.info(hint)
-}
-
-const plugin_install_hint_module = {
-	is_plugin_installed,
-	plugin_install_hint,
-	report_plugin_install_hint,
-}
-
-export { plugin_install_hint_module }

package/scripts/version/parse-json.ts

@@ -1,13 +0,0 @@
-// Parse JSON without throwing: returns the parsed value, or undefined when the input is not valid
-// JSON. Single source for the version commands that read package.json / CLI output and hand the
-// result to a schema's `safeParse` (running-binary, version-targets, effective-upstream), so the
-// permissive-parse behavior is defined once rather than re-cloned per reader.
-function safe_json_parse(raw: string): unknown {
-	try {
-		return JSON.parse(raw)
-	} catch {
-		return undefined
-	}
-}
-
-export { safe_json_parse }