@joshuafolkken/kit 1.872.0

package/scripts/init/init-logic.ts

@@ -0,0 +1,474 @@
+import { json_format } from '#scripts/config-merge/json-format'
+import { vscode_settings_schema } from '#scripts/lib/schemas'
+import { distributed_paths } from './distributed-paths'
+import { init_logic_deploy_vps } from './init-logic-deploy-vps'
+import { init_logic_json_merge } from './init-logic-json-merge'
+import { init_logic_secretlint } from './init-logic-secretlint'
+import { init_logic_sonar } from './init-logic-sonar'
+import { init_logic_templates } from './init-logic-templates'
+import { init_logic_workspace } from './init-logic-workspace'
+import { init_logic_yaml_merge } from './init-logic-yaml-merge'
+
+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.
+const NPMRC_LINES: ReadonlyArray<string> = [
+	'@joshuafolkken:registry=https://npm.pkg.github.com',
+	'engine-strict=true',
+	'minimum-release-age=1440',
+	'confirmModulesPurge=false',
+	// Pin full GitHub Packages tarball URLs in the lockfile so pnpm >=11.5 frozen-lockfile
+	// installs hit the correct authenticated download path (avoids ERR_PNPM_FETCH_401 on CI).
+	'lockfile-include-tarball-url=true',
+]
+
+const CSPELL_IMPORT = '@joshuafolkken/kit/cspell'
+
+const LEFTHOOK_INSTALL_CMD = 'lefthook install'
+const SAFE_CHAIN_CMD = 'pnpm dlx @aikidosec/safe-chain setup-ci'
+const FIX_GH_PACKAGES_CMD = 'tsx node_modules/@joshuafolkken/kit/scripts/gh/fix-gh-packages.ts'
+// Marker identifying a consumer script that already runs the fix-gh-packages command.
+const FIX_GH_PACKAGES_MARKER = 'fix-gh-packages'
+const PREPARE_KEY = 'prepare'
+// Legacy key: earlier `josh init` runs injected the lifecycle commands here. We now
+// migrate a kit-managed `postinstall` (one containing fix-gh-packages) to `prepare`.
+const LEGACY_POSTINSTALL_KEY = 'postinstall'
+// Guard each command so a missing binary (production / CI installs without dev deps,
+// global installs outside a git repo) does not abort `pnpm install`. These are
+// developer-only hooks, so they live in `prepare` (local install + pack/publish)
+// rather than `postinstall`, which also runs when the package is a consumer dependency.
+// A failing `lefthook install` used to be indistinguishable from a missing binary: `|| true` swallowed
+// both, so an install that left **zero** hooks in place still exited 0 and said nothing. The way it
+// happens in practice is `core.hooksPath` — lefthook refuses to install while any custom hooks path is
+// set — and the developer then commits and pushes for weeks with no pre-commit or pre-push check
+// running at all, believing they are (joshuafolkken/kit#1503).
+//
+// **The `|| true` stays**: a consumer's `pnpm install` must not die over a developer-only hook, which
+// is what it was added for. What changes is that the failure is named on standard error. The warning
+// sits **inside the branch the binary check already gates**, which is what separates the two cases —
+// the ordinary production or CI install, where lefthook is simply absent, stays exactly as silent as
+// it was, and only "lefthook is here and could not install" speaks up.
+// **It names a likely cause rather than asserting one, and links a URL rather than a path.** A set
+// `core.hooksPath` is much the commonest reason, but not the only one — a dev-dependency install in a
+// container with no `.git` fails here too — so a message that diagnosed would misdiagnose that build
+// on every run. And `docs/` is not among the files `josh init` copies, so a consumer told to read
+// `docs/init.md` is told to open a file their repository does not contain.
+const HOOK_INSTALL_WARNING =
+	'lefthook install failed: git hooks are NOT installed. A set core.hooksPath is the usual cause. See https://github.com/joshuafolkken/kit/blob/main/docs/init.md#corehookspath-stops-lefthook-installing-anything'
+const LEFTHOOK_BINARY_GUARD = 'command -v lefthook >/dev/null 2>&1'
+const GUARDED_LEFTHOOK_CMD = `${LEFTHOOK_BINARY_GUARD} && { ${LEFTHOOK_INSTALL_CMD} || echo '${HOOK_INSTALL_WARNING}' >&2; }`
+// What every already-initialized consumer has in `prepare` today, and what the upgrade below rewrites.
+const LEGACY_GUARDED_LEFTHOOK_CMD = `${LEFTHOOK_BINARY_GUARD} && ${LEFTHOOK_INSTALL_CMD}`
+const GUARDED_FIX_GH_PACKAGES_CMD = `command -v tsx >/dev/null 2>&1 && ${FIX_GH_PACKAGES_CMD}`
+// Tolerate each optional hook individually with `|| true` and chain them with `&&`,
+// rather than a blanket trailing `; true`. A blanket `; true` is reached
+// unconditionally, so it masks failures of the core steps this command is appended
+// to (e.g. `pnpm gen && svelte-kit sync`). Per-command tolerance keeps those core
+// steps fail-fast while a missing `lefthook`/`tsx` (or a failing optional hook) still
+// exits zero.
+const PREPARE_CMD = `(${GUARDED_LEFTHOOK_CMD} || true) && (${GUARDED_FIX_GH_PACKAGES_CMD} || true)`
+
+// CLAUDE.md is deliberately absent: it is no longer byte-copied. A consumer's CLAUDE.md is a single
+// @import of kit's published, path-transformed rules (ensure_claude_md_import), so a package update
+// alone keeps it current (joshuafolkken/kit#1878). AGENTS.md / GEMINI.md / .cursorrules stay copies
+// here — they are for other tools that do not read CLAUDE.md's import.
+const AI_COPY_FILES: ReadonlyArray<string> = [
+	'AGENTS.md',
+	'GEMINI.md',
+	'CODE_OF_CONDUCT.md',
+	'.cursorrules',
+	'.coderabbit.yaml',
+	'.gitattributes',
+	'.mcp.json',
+	'.ncurc.json',
+	'.prettierignore',
+	'SECURITY.md',
+	'pnpm-workspace.yaml',
+	'tsconfig.sonar.json',
+	'.github/workflows/auto-tag.yml',
+	'.github/workflows/production.yml',
+	'.github/workflows/sonar-qube.yml',
+	'.github/pull_request_template.md',
+	'.github/release.yml',
+	'.github/dependabot.yml',
+	'.claude/settings.json',
+	'.codex/config.toml',
+	'.codex/hooks.json',
+]
+
+interface FileCopyMapping {
+	src: string
+	dest: string
+}
+
+// `.gitignore` is intentionally NOT a byte-copy mapping — it is union-merged via
+// merge_gitignore (init-actions build_file_actions + sync_configs.sync_gitignore) so
+// consumer-local entries survive a sync. Only fully-managed files consumers never
+// hand-edit stay here.
+const AI_COPY_FILE_MAPPINGS: ReadonlyArray<FileCopyMapping> = [
+	{ src: 'templates/workflows/ci.yml', dest: '.github/workflows/ci.yml' },
+	// The counterpart to the distributed `.github/dependabot.yml`: without it a consumer receives
+	// the machinery that opens Dependabot pull requests and none of the machinery that closes them,
+	// so every github-actions bump sits green and unmerged (joshuafolkken/kit#834).
+	{
+		src: 'templates/workflows/dependabot-auto-merge.yml',
+		dest: '.github/workflows/dependabot-auto-merge.yml',
+	},
+]
+
+// Empty since joshuafolkken/kit#1879: the five skill directories kit used to copy whole
+// (`workflow-commands`, `epic-commands`, `dependency-update`, `verify-ui`, `diag`) now ship as the
+// `kit` Claude Code plugin and load from the package, so nothing is copied into a consumer's tree.
+// The copy-and-transform machinery (directory-copy-guard.ts → transform_copied_tree) is kept intact
+// for any future distributed directory; the migration that removes a consumer's stale skill copies
+// lives in `scripts/sync/skill-migration.ts`.
+const AI_COPY_DIRECTORIES: ReadonlyArray<string> = []
+
+const LEFTHOOK_EXTENDS = 'node_modules/@joshuafolkken/kit/lefthook/vanilla.yml'
+
+// The preset MUST keep a `.json` extension: Playwright (>= 1.62) appends `.json` to any tsconfig
+// `extends` entry that does not already end in it, then hard-throws when the resulting path is
+// missing — so a `.jsonc` preset resolves to `*.jsonc.json` and takes down the whole E2E suite
+// before a single test runs. A tsconfig is parsed as JSONC regardless of extension, so comments in
+// the preset still work. See joshuafolkken/kit#681.
+const TSCONFIG_EXTENDS = './node_modules/@joshuafolkken/kit/tsconfig/base.json'
+
+// Preset file basename within the package's tsconfig/ directory, used to read the base
+// compilerOptions when normalizing a consumer tsconfig.json during sync.
+const TSCONFIG_PRESET_FILENAME = 'base.json'
+
+const TSCONFIG_EXCLUDE_FIELD = 'exclude'
+
+// Directories the kit-distributed configs generate, plus the usual build outputs. `playwright.config.ts`
+// points the html reporter at `playwright-report/` and Playwright writes `test-results/` — the report
+// holds Playwright's own minified trace-viewer bundle, so a consumer with a broad `include` gets
+// thousands of tsc errors from third-party output right after running the E2E suite kit ships the
+// config for. The two directories must stay disjoint (Playwright refuses an html output folder nested
+// in the tests output folder, and vice versa), so both are excluded rather than consolidated. These
+// belong in the CONSUMER file: a consumer `exclude` overrides the extended preset's instead of merging
+// with it, so shipping them only in a preset would have no effect. See joshuafolkken/kit#712.
+const TSCONFIG_GENERATED_OUTPUT_EXCLUDE: ReadonlyArray<string> = [
+	'node_modules',
+	'build',
+	'dist',
+	'playwright-report',
+	'test-results',
+]
+
+// The service-worker globs `.svelte-kit/tsconfig.json` excludes, rewritten relative to the consumer
+// root (SvelteKit writes them `../`-prefixed from inside `.svelte-kit/`). They must be repeated here
+// for the same reason the entries above live in the consumer file, read in the other direction: a
+// consumer `exclude` REPLACES the extended config's array rather than merging with it, so the moment
+// kit writes any `exclude` key, every one of SvelteKit's own exclusions is discarded. SvelteKit keeps
+// the service worker out of the app program deliberately — it runs in a worker context with its own
+// `lib` (`WebWorker`, not `DOM`) and its own generated `$service-worker` ambient types, so
+// type-checking it under the app config produces errors with no correct fix from inside that config.
+// Carrying them forward makes kit's array additive. They are written unconditionally: these are pure
+// string transforms with no view of the project, kit has no SvelteKit detection anywhere, and at
+// `josh init` time the generated config does not exist yet to be read. The cost lands on a
+// NON-SvelteKit consumer that keeps its own `src/service-worker.ts` — a program root nothing imports,
+// so excluding it drops it from `tsc --noEmit`, and a re-sync re-adds the globs if they are deleted.
+// Such a project needs a separate tsconfig for that file regardless, since worker code wants
+// `lib: WebWorker` rather than the app's `DOM`. `../node_modules/**` is the one entry not repeated —
+// `node_modules` above already covers it.
+//
+// Limit: these are the DEFAULT paths. A project that moves the worker with `kit.files.serviceWorker`
+// in `svelte.config.js` gets globs that match nothing, and its real exclusion is still replaced — the
+// #796 failure, unfixed for that shape. Covering it means reading `svelte.config.js`, which is the
+// same project detection kit does not have; such a project should add its own path to `exclude`
+// (the merge appends, so a hand-added entry survives). See joshuafolkken/kit#796.
+const TSCONFIG_SVELTEKIT_EXCLUDE: ReadonlyArray<string> = [
+	'src/service-worker.js',
+	'src/service-worker/**/*.js',
+	'src/service-worker.ts',
+	'src/service-worker/**/*.ts',
+	'src/service-worker.d.ts',
+	'src/service-worker/**/*.d.ts',
+]
+
+const TSCONFIG_EXCLUDE: ReadonlyArray<string> = [
+	...TSCONFIG_GENERATED_OUTPUT_EXCLUDE,
+	...TSCONFIG_SVELTEKIT_EXCLUDE,
+]
+
+// extensions.json is distributed in common across project styles, so it is not keyed by type.
+const VSCODE_EXTENSIONS_FILENAME = 'extensions.json'
+
+const VSCODE_SETTINGS_FILENAME = 'settings.json'
+
+// Keys that exist in the kit's own .vscode/settings.json for kit development but must
+// never be distributed to consumer projects (e.g. SonarLint connected-mode points at the
+// kit's own SonarQube project under the kit author's connection id).
+const KIT_ONLY_VSCODE_SETTINGS_KEYS: ReadonlySet<string> = new Set([
+	'sonarlint.connectedMode.project',
+])
+
+const SUGGESTED_SCRIPTS_COMMON: Record<string, string> = {
+	preinstall: SAFE_CHAIN_CMD,
+	prepare: PREPARE_CMD,
+	josh: 'josh',
+}
+
+// prettier resolves its `plugins[]` from the consumer project, not transitively through the kit,
+// so every package that uses the kit prettier preset must declare these as devDependencies. The
+// preset references all three unconditionally (prettier/index.js → plugins), hence all three are
+// added regardless of project — omitting any breaks `prettier`/`josh lint` with a
+// "Cannot find package" error. Versions mirror the kit's own devDependencies.
+const SORT_IMPORTS_PLUGIN_KEY = '@ianvs/prettier-plugin-sort-imports'
+const PRETTIER_SVELTE_PLUGIN_KEY = 'prettier-plugin-svelte'
+const PRETTIER_TAILWIND_PLUGIN_KEY = 'prettier-plugin-tailwindcss'
+const PRETTIER_PLUGIN_DEV_DEPS: Record<string, string> = {
+	[SORT_IMPORTS_PLUGIN_KEY]: '^4.7.1',
+	[PRETTIER_SVELTE_PLUGIN_KEY]: '^4.1.1',
+	[PRETTIER_TAILWIND_PLUGIN_KEY]: '^0.8.0',
+}
+
+// format_json rather than JSON.stringify: it lays arrays out the way prettier does — inline while
+// they fit within printWidth, one element per line once they do not — so the file kit writes is
+// `prettier --check`-clean in the consumer whatever the entry count happens to be (#660).
+function generate_tsconfig(): string {
+	return json_format.format_json({
+		extends: TSCONFIG_EXTENDS,
+		[TSCONFIG_EXCLUDE_FIELD]: TSCONFIG_EXCLUDE,
+	})
+}
+
+// Union-merge kit's generated-output entries into an existing consumer `exclude`: entries the
+// consumer authored are kept verbatim and only the missing ones are appended, so an already-merged
+// file is a no-op. Insert-if-absent on the file as a whole would never repair the installed base,
+// which is the whole point here — every current consumer has a tsconfig already.
+function merge_tsconfig_exclude(content: string): string {
+	const field = TSCONFIG_EXCLUDE_FIELD
+
+	return init_logic_json_merge.merge_json_array_field(content, field, TSCONFIG_EXCLUDE)
+}
+
+function generate_lefthook_config(): string {
+	return `extends:\n  - ${LEFTHOOK_EXTENDS}\n`
+}
+
+function generate_cspell_config(): string {
+	return `version: "0.2"\nimport:\n  - "${CSPELL_IMPORT}"\nwords: []\nignorePaths: []\n`
+}
+
+function generate_npmrc(): string {
+	return `${NPMRC_LINES.join('\n')}\n`
+}
+
+// Append `missing` lines to `existing`, inserting a separating newline when the base is
+// non-empty and lacks a trailing one. Returns `existing` untouched when nothing is missing.
+function append_missing_lines(existing: string, missing: ReadonlyArray<string>): string {
+	if (missing.length === 0) return existing
+	const prefix = existing.length > 0 && !existing.endsWith('\n') ? `${existing}\n` : existing
+
+	return `${prefix}${missing.join('\n')}\n`
+}
+
+// Insert-only: every existing line survives verbatim, including a `_authToken` line the consumer
+// added themselves. Kit removed the env-var form until #759, on the premise that pnpm always
+// ignores it in a project .npmrc — true only while `npmrcAuthFile` is unset. A consumer that
+// declares the project file its trusted auth file (Cloudflare Workers Builds via
+// `PNPM_CONFIG_NPMRC_AUTH_FILE`, for instance) gets the credential expanded, and that setting can
+// live in a deploy platform's dashboard — so no reading of the repository tells an inert line
+// apart from a live one. Deleting it took down a working production deploy; leaving it costs at
+// most the warning pnpm already prints. See docs/authentication.md §4(d).
+function merge_npmrc(content: string): string {
+	const missing = NPMRC_LINES.filter((line) => !content.includes(line))
+
+	return append_missing_lines(content, missing)
+}
+
+// A gitignore line worth appending during a union merge: real ignore patterns only.
+// Comments and blank lines are skipped so re-syncing never accumulates orphaned section
+// headers detached from their entries.
+function is_gitignore_pattern(line: string): boolean {
+	const trimmed = line.trim()
+
+	return trimmed.length > 0 && !trimmed.startsWith('#')
+}
+
+// Union-merge the kit .gitignore template into an existing consumer file: keep every
+// consumer line verbatim and append only the template patterns not already present.
+// Matching is per-line (not substring) so `.env` is still appended when only `.env.local`
+// exists. Order-stable and idempotent — re-running on an already-merged file is a no-op.
+function merge_gitignore(existing: string, template: string): string {
+	const existing_lines = new Set(existing.split('\n'))
+	const missing = template
+		.split('\n')
+		.filter((line) => is_gitignore_pattern(line) && !existing_lines.has(line))
+
+	return append_missing_lines(existing, missing)
+}
+
+function get_tsconfig_extends_entry(): string {
+	return TSCONFIG_EXTENDS
+}
+
+function get_tsconfig_preset_filename(): string {
+	return TSCONFIG_PRESET_FILENAME
+}
+
+function get_tsconfig_exclude_entries(): ReadonlyArray<string> {
+	return TSCONFIG_EXCLUDE
+}
+
+function get_lefthook_extends_value(): string {
+	return LEFTHOOK_EXTENDS
+}
+
+function get_cspell_import_value(): string {
+	return CSPELL_IMPORT
+}
+
+function get_vscode_settings_filename(): string {
+	return VSCODE_SETTINGS_FILENAME
+}
+
+function strip_kit_only_vscode_settings(
+	settings: Record<string, unknown>,
+): Record<string, unknown> {
+	const entries = Object.entries(settings).filter(
+		([key]) => !KIT_ONLY_VSCODE_SETTINGS_KEYS.has(key),
+	)
+
+	return Object.fromEntries(entries)
+}
+
+function strip_kit_only_vscode_settings_content(raw: string): string {
+	const parsed = vscode_settings_schema.parse(JSON.parse(raw))
+	const stripped = strip_kit_only_vscode_settings(parsed)
+	if (Object.keys(stripped).length === Object.keys(parsed).length) return raw
+
+	// format_json, not plain JSON.stringify: prettier reads `.vscode/settings.json` with the `json`
+	// parser, which keeps a short array such as `eslint.validate` inline. Expanding it here wrote a
+	// file the consumer's own `prettier --check` rejects — the same defect as kit#797, which was
+	// about the opposite direction on `package.json`.
+	return json_format.format_json(stripped)
+}
+
+function get_npmrc_lines(): ReadonlyArray<string> {
+	return NPMRC_LINES
+}
+
+function get_development_engines_value(): typeof DEV_ENGINES_VALUE {
+	return DEV_ENGINES_VALUE
+}
+
+function get_ai_copy_files(): ReadonlyArray<string> {
+	return AI_COPY_FILES
+}
+
+function get_ai_copy_file_mappings(): ReadonlyArray<FileCopyMapping> {
+	return AI_COPY_FILE_MAPPINGS
+}
+
+function get_ai_copy_directories(): ReadonlyArray<string> {
+	return AI_COPY_DIRECTORIES
+}
+
+function get_suggested_scripts(): Record<string, string> {
+	return SUGGESTED_SCRIPTS_COMMON
+}
+
+// Drop the suggested `prepare` when the consumer already runs fix-gh-packages in
+// any script, so re-running `josh init` does not re-inject a duplicate hook that
+// fights the consumer's intentional consolidation.
+function get_suggested_scripts_for_content(content: string): Record<string, string> {
+	const scripts = get_suggested_scripts()
+	const has_fix = init_logic_json_merge.has_package_scripts_marker(content, FIX_GH_PACKAGES_MARKER)
+	if (!has_fix) return scripts
+
+	return Object.fromEntries(Object.entries(scripts).filter(([key]) => key !== PREPARE_KEY))
+}
+
+// **The upgrade path for projects `josh init` has already run in.** Their `prepare` carries the
+// fix-gh-packages marker, and that marker is exactly what makes both merges here return early — so
+// the population joshuafolkken/kit#1503 is actually about, the consumers already installing with zero
+// hooks and no warning, would never receive the fix however often they re-ran `josh init`; only new
+// projects would. This rewrites the lefthook clause kit itself wrote and nothing else, because the
+// rest of that script is the consumer's. It is idempotent by construction: the new clause does not
+// contain the old one as a substring, since `{ ` sits between them.
+function upgrade_prepare_lefthook_warning(content: string): string {
+	return init_logic_json_merge.replace_in_package_script(
+		content,
+		PREPARE_KEY,
+		LEGACY_GUARDED_LEFTHOOK_CMD,
+		GUARDED_LEFTHOOK_CMD,
+	)
+}
+
+// Append the guarded lifecycle commands to an existing `prepare` when no script yet runs
+// fix-gh-packages, so the dev-only hooks land in `prepare` instead of being lost when the
+// suggested-scripts merge skips the already-present `prepare` key.
+function merge_prepare_lifecycle_cmd(content: string): string {
+	const has_fix = init_logic_json_merge.has_package_scripts_marker(content, FIX_GH_PACKAGES_MARKER)
+	if (has_fix) return content
+
+	return init_logic_json_merge.merge_package_script_suffix(content, PREPARE_KEY, PREPARE_CMD)
+}
+
+// Migration: remove a kit-managed `postinstall` (one running the fix-gh-packages
+// command) so the lifecycle can be re-added to `prepare`. Matching the full command
+// rather than the bare marker avoids stripping a consumer's unrelated postinstall that
+// merely mentions `fix-gh-packages` (e.g. `npm run my-fix-gh-packages-helper`).
+function strip_managed_postinstall(content: string): string {
+	return init_logic_json_merge.remove_script_with_marker(
+		content,
+		LEGACY_POSTINSTALL_KEY,
+		FIX_GH_PACKAGES_CMD,
+	)
+}
+
+function merge_prettier_plugin_development_deps(content: string): string {
+	return init_logic_json_merge.merge_development_dependencies(content, PRETTIER_PLUGIN_DEV_DEPS)
+}
+
+const init_logic = {
+	...init_logic_templates,
+	...init_logic_workspace,
+	...init_logic_sonar,
+	...init_logic_json_merge,
+	...init_logic_secretlint,
+	...init_logic_yaml_merge,
+	...init_logic_deploy_vps,
+	...distributed_paths,
+	generate_tsconfig,
+	merge_tsconfig_exclude,
+	get_tsconfig_exclude_entries,
+	generate_lefthook_config,
+	generate_cspell_config,
+	generate_npmrc,
+	merge_npmrc,
+	merge_gitignore,
+	merge_prettier_plugin_development_deps,
+	get_tsconfig_extends_entry,
+	get_tsconfig_preset_filename,
+	get_lefthook_extends_value,
+	get_cspell_import_value,
+	get_vscode_settings_filename,
+	strip_kit_only_vscode_settings,
+	strip_kit_only_vscode_settings_content,
+	VSCODE_EXTENSIONS_FILENAME,
+	GUARDED_LEFTHOOK_CMD,
+	upgrade_prepare_lefthook_warning,
+	get_npmrc_lines,
+	get_development_engines_value,
+	get_ai_copy_files,
+	get_ai_copy_file_mappings,
+	get_ai_copy_directories,
+	get_suggested_scripts,
+	get_suggested_scripts_for_content,
+	merge_prepare_lifecycle_cmd,
+	strip_managed_postinstall,
+}
+
+export { init_logic }
+export type { SonarIdentifiers } from './init-logic-sonar'

package/scripts/init/init-paths.ts

@@ -0,0 +1,11 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const PROJECT_ROOT = process.cwd()
+
+function package_path(relative_path: string): string {
+	return path.join(PACKAGE_DIR, relative_path)
+}
+
+export { PACKAGE_DIR, PROJECT_ROOT, package_path }

package/scripts/init/init-sonar.ts

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { sonar_file } from '#scripts/security/sonar-file'
+import { init_logic } from './init-logic'
+import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
+
+function copy_sonar_with_template(name_with_owner: string | undefined): void {
+	const destination = init_logic.get_sonar_template_destination()
+
+	if (name_with_owner === undefined) {
+		console.warn(`  ⚠ skipped   ${destination} (gh repo view failed)`)
+
+		return
+	}
+
+	const destination_path = path.join(PROJECT_ROOT, destination)
+	const is_existing = existsSync(destination_path)
+	const identifiers = init_logic.derive_sonar_identifiers(name_with_owner)
+
+	sonar_file.merge_sonar_file(
+		path.join(PACKAGE_DIR, init_logic.get_sonar_template_source()),
+		destination_path,
+		identifiers,
+	)
+	console.info(`  ✔ ${is_existing ? 'updated' : 'created'}   ${destination}`)
+}
+
+const init_sonar = {
+	copy_sonar_with_template,
+}
+
+export { init_sonar }