@joshuafolkken/kit 1.872.0 → 1.879.0

package/.github/workflows/publish.yml

@@ -5,7 +5,7 @@ on:
     types: [new-tag-created]
 
 jobs:
-  publish:
+  publish-github:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
@@ -13,6 +13,8 @@ jobs:
       packages: write
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.client_payload.tag }}
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
@@ -34,6 +36,41 @@ jobs:
 
       - run: pnpm install --frozen-lockfile --ignore-scripts
 
-      - run: pnpm publish --no-git-checks --tag latest
+      - run: pnpm publish --no-git-checks --tag latest --registry https://npm.pkg.github.com
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-npm:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.client_payload.tag }}
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Resolve pnpm version
+        id: pnpm-version
+        run: |
+          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
+          test -n "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          version: ${{ steps.pnpm-version.outputs.version }}
+          install: false
+
+      - run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - run: pnpm pack --out "$RUNNER_TEMP/kit.tgz"
+
+      - name: Publish to npm
+        run: cd "$RUNNER_TEMP" && npm publish kit.tgz --access public --tag latest --registry https://registry.npmjs.org --userconfig /dev/null

package/README.md

@@ -8,12 +8,11 @@ Shared toolchain config and CLI for TypeScript projects — ESLint, Prettier, Ty
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) with [pnpm](https://pnpm.io/)
-- [gh CLI](https://cli.github.com/) — required for GitHub Packages authentication. Install via `brew install gh` (macOS), `winget install GitHub.cli` (Windows), or see the [gh installation docs](https://github.com/cli/cli#installation).
+- [gh CLI](https://cli.github.com/) for `josh version` and existing GitHub Packages consumers. It is not required to install kit from public npm; see [authentication.md](./docs/authentication.md) for setup when needed.
 
 ## Quick start
 
 ```bash
-gh auth login --scopes read:packages   # see docs/authentication.md for the full setup
 pnpm add -g @joshuafolkken/kit          # install the josh CLI globally
 josh help
 ```
@@ -25,9 +24,10 @@ Using the kit inside a project? See [docs/package.md](./docs/package.md).
 | Guide                                           | What it covers                                                                   |
 | ----------------------------------------------- | -------------------------------------------------------------------------------- |
 | [why.md](./docs/why.md)                         | Why kit exists — the AI-development problems it solves, for practitioners        |
-| [authentication.md](./docs/authentication.md)   | One-time GitHub Packages auth — `gh` token, `NODE_AUTH_TOKEN`, `.npmrc`          |
+| [authentication.md](./docs/authentication.md)   | GitHub Packages auth for existing projects                                       |
 | [cli.md](./docs/cli.md)                         | Install and use the global `josh` CLI                                            |
 | [package.md](./docs/package.md)                 | Use the kit as a project devDependency — configs, prompts, scripts, `josh init`  |
+| [publishing.md](./docs/publishing.md)           | First public npm release and trusted publishing setup                            |
 | [josh-commands.md](./docs/josh-commands.md)     | Full `josh` CLI command reference                                                |
 | [overview.md](./docs/overview.md)               | What the kit provides and how it works                                           |
 | [troubleshooting.md](./docs/troubleshooting.md) | `401`/`404` auth errors, `josh: command not found`, stale shim, version mismatch |

package/package.json

@@ -1,8 +1,12 @@
 {
-  "version": "1.872.0",
+  "version": "1.879.0",
   "name": "@joshuafolkken/kit",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joshuafolkken/kit.git"
+  },
   "engines": {
     "node": ">=22.19.0"
   },
@@ -166,4 +170,4 @@
     "build": "tsx scripts/build/build-bin.ts && tsx scripts/build/build-hooks.ts && tsx scripts/build/build-version.ts && tsx scripts/build/build-config-merge.ts && tsx scripts/build/build-managed-marker.ts && tsx scripts/build/build-self-sync-guard.ts && tsx scripts/build/build-claude-md.ts",
     "josh": "tsx scripts/josh/josh.ts"
   }
-}
+}

package/scripts/init/distributed-paths.ts

@@ -17,11 +17,11 @@ const ESLINT_PACKAGE_PREFIX = `${KIT_PACKAGE_PATH_PREFIX}eslint/`
 const GITHUB_REPO_BLOB_BASE = 'https://github.com/joshuafolkken/kit/blob/main/'
 const GITHUB_REPO_TREE_BASE = 'https://github.com/joshuafolkken/kit/tree/main/'
 
-// The single line a consumer's CLAUDE.md carries: an import of kit's published, already
-// path-transformed rules. The consumer's own additions sit below it. Distributed at publish time via
-// dist/CLAUDE.md (build-claude-md.ts) rather than byte-copied at sync time, so a package update alone
-// keeps the rules current (joshuafolkken/kit#1878).
+// The consumer imports kit's published, already path-transformed rules. A tracked bootstrap note
+// remains readable before installation, while the rule body stays in the package (kit#1878).
 const CLAUDE_MD_IMPORT_LINE = '@node_modules/@joshuafolkken/kit/dist/CLAUDE.md'
+const CLAUDE_MD_BOOTSTRAP =
+	'> Fresh checkout: if kit is not installed, run `pnpm install` first, then reread this file before doing any other work.'
 
 // A span containing `*` is excluded: it is a **glob**, not a reference to a file a consumer can
 // open. A distributed document that writes a directory set as `prompts/**` means "anything beneath
@@ -79,15 +79,18 @@ function transform_distributed_paths(content: string): string {
 	return transform_documentation_paths(with_tests)
 }
 
-// The consumer CLAUDE.md is one @import of kit's published rules plus whatever the project adds below
-// it. Ensure the import line is present without disturbing those additions: an absent file becomes
-// the line alone, a file already carrying it is returned untouched, and any other file keeps all its
-// content with the import prepended. The substring check makes it idempotent.
+// Keep the bootstrap note ahead of the import so an agent can read it in a fresh checkout. Preserve
+// project additions and update older one-line files without duplicating either line.
 function ensure_claude_md_import(existing: string | undefined): string {
-	if (existing === undefined) return `${CLAUDE_MD_IMPORT_LINE}\n`
-	if (existing.includes(CLAUDE_MD_IMPORT_LINE)) return existing
+	if (existing === undefined) return `${CLAUDE_MD_BOOTSTRAP}\n\n${CLAUDE_MD_IMPORT_LINE}\n`
 
-	return `${CLAUDE_MD_IMPORT_LINE}\n\n${existing}`
+	if (existing.includes(CLAUDE_MD_IMPORT_LINE)) {
+		if (existing.includes(CLAUDE_MD_BOOTSTRAP)) return existing
+
+		return `${CLAUDE_MD_BOOTSTRAP}\n\n${existing}`
+	}
+
+	return `${CLAUDE_MD_BOOTSTRAP}\n\n${CLAUDE_MD_IMPORT_LINE}\n\n${existing}`
 }
 
 const distributed_paths = {

package/scripts/init/hook-command-bootstrap.ts

@@ -0,0 +1,51 @@
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { git_location_environment } from '#scripts/git/git-location-environment'
+
+interface HookResult {
+	status: number | null
+	stdout: string
+	stderr: string
+}
+
+function create_partial_install(temporary_root: string): void {
+	const package_root = path.join(temporary_root, 'node_modules/@joshuafolkken/kit')
+	const hook_path = path.join(package_root, 'dist/hooks/pretool-guard.js')
+
+	mkdirSync(path.dirname(hook_path), { recursive: true })
+	writeFileSync(path.join(package_root, 'package.json'), '{}')
+	writeFileSync(hook_path, "process.stdout.write('guard ran')")
+}
+
+function run_in_temporary_checkout(command: string, is_partial_install = false): HookResult {
+	const temporary_root = mkdtempSync(path.join(tmpdir(), 'kit-hook-bootstrap-'))
+	const git_environment = {
+		...process.env,
+		...git_location_environment.location_free_environment(),
+	}
+
+	try {
+		spawnSync('git', ['init', '-q'], {
+			cwd: temporary_root,
+			env: git_environment,
+		})
+
+		if (is_partial_install) create_partial_install(temporary_root)
+
+		const { status, stdout, stderr } = spawnSync('sh', ['-c', command], {
+			cwd: temporary_root,
+			encoding: 'utf8',
+			env: git_environment,
+		})
+
+		return { status, stdout, stderr }
+	} finally {
+		rmSync(temporary_root, { recursive: true, force: true })
+	}
+}
+
+const hook_command_bootstrap = { run_in_temporary_checkout }
+
+export { hook_command_bootstrap }

package/scripts/init/hook-command-rewrite.ts

@@ -21,6 +21,9 @@ const BUNDLE_INVOCATION = `node ${claude_plugin_config.MARKETPLACE_PATH}/dist/jo
 // The per-hook bundle directory a fresh clone builds, and where it lives inside the installed package.
 const HOOK_BUNDLE_DIR = `${hook_launch.HOOK_DIST_DIR}/`
 const CONSUMER_HOOK_BUNDLE_DIR = `${claude_plugin_config.MARKETPLACE_PATH}/${HOOK_BUNDLE_DIR}`
+const CONSUMER_PACKAGE_MANIFEST = `${claude_plugin_config.MARKETPLACE_PATH}/package.json`
+const MISSING_INSTALL_NOTICE = 'kit hooks inactive: run pnpm install, then reread CLAUDE.md'
+const MISSING_INSTALL_GUARD = `if [ ! -f ${CONSUMER_PACKAGE_MANIFEST} ]; then echo '${MISSING_INSTALL_NOTICE}' >&2; exit 0; fi; `
 const CODEX_ADAPTER_BUNDLE = `node ${CONSUMER_HOOK_BUNDLE_DIR}codex-hook-adapter.js`
 const CODEX_HOOKS_DESTINATION = '.codex/hooks.json'
 const CODEX_ROOT_PREFIX = String.raw`cd \"$(git rev-parse --show-toplevel)\" && `
@@ -43,11 +46,16 @@ function rebase_bundle_directory(value: string): string {
 // independent whichever order they run. The fallback rewrite is idempotent too (`BUNDLE_INVOCATION`
 // holds no `pnpm josh `), so the whole rewrite is safe to run more than once.
 function rewrite_command_value(value: string): string {
-	return rebase_bundle_directory(value)
+	const rewritten = rebase_bundle_directory(value)
 		.split(PNPM_JOSH_PREFIX)
 		.join(BUNDLE_INVOCATION)
 		.split(CODEX_ADAPTER_SOURCE)
 		.join(CODEX_ADAPTER_BUNDLE)
+
+	if (!rewritten.includes(claude_plugin_config.MARKETPLACE_PATH)) return rewritten
+	if (rewritten.includes(MISSING_INSTALL_GUARD)) return rewritten
+
+	return `${MISSING_INSTALL_GUARD}${rewritten}`
 }
 
 function rewrite_hook_commands(content: string, is_codex = false): string {

package/scripts/init/init-logic.ts

@@ -13,15 +13,9 @@ const DEV_ENGINES_VALUE = {
 	packageManager: { name: 'pnpm', version: '>=12.1.0', onFail: 'error' },
 }
 
-// The `@joshuafolkken:registry` mapping stays — it is a registry mapping, not a credential,
-// and pnpm honors it from a project .npmrc unconditionally. The matching `_authToken` line is
-// deliberately absent: by default pnpm >= 11.6 refuses to expand environment variables in
-// credentials read from a project .npmrc (the file is committed, so expansion could leak the
-// token to an attacker-controlled registry), so distributing the line would only add an
-// `Ignored project-level auth setting` warning on every command. Not distributing it is not the
-// same as removing it — see merge_npmrc.
+// New projects resolve kit from public npm. Existing registry and auth lines remain untouched
+// by merge_npmrc so consumers of other GitHub Packages can migrate separately.
 const NPMRC_LINES: ReadonlyArray<string> = [
-	'@joshuafolkken:registry=https://npm.pkg.github.com',
 	'engine-strict=true',
 	'minimum-release-age=1440',
 	'confirmModulesPurge=false',

package/templates/workflows/ci.yml

@@ -118,7 +118,9 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: '24'
-          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Configure GitHub Packages authentication for existing projects
+        run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
 
       - name: Resolve pnpm version
         id: pnpm-version
@@ -358,7 +360,9 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: '24'
-          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Configure GitHub Packages authentication for existing projects
+        run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
 
       - name: Resolve pnpm version
         id: pnpm-version