@joshuafolkken/kit 1.1383.0 → 1.1435.0

package/scripts/uninstall/uninstall-plan.ts

@@ -0,0 +1,119 @@
+import { json_format } from '#scripts/config-merge/json-format'
+import { json_value } from '#scripts/lib/json-value'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+
+// One file kit writes into a project, with the content it writes there. `distributed` is absent when
+// that content cannot be worked out here — a file whose text depends on the repository it lands in,
+// read where there is no such repository — and such a file is never one this command may delete.
+interface DistributedFile {
+	dest: string
+	distributed: string | undefined
+}
+
+interface FilePlan {
+	remove: Array<string>
+	keep: Array<string>
+}
+
+type ReadFile = (destination: string) => string | undefined
+
+// Never deleted, even while it is still what kit wrote: without it the `.env` and `node_modules` it
+// kept out of Git turn into untracked files, and the next `git add -A` stages them.
+const IGNORE_FILE = '.gitignore'
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies']
+const JOSH_FIELD = 'josh'
+const PROFILE_FIELD = 'profile'
+// `strip_kit` takes kit's own entry back out of this field, so it is not left for a person to review.
+const HANDLED_FIELDS: ReadonlySet<string> = new Set([JOSH_FIELD])
+
+// A file is deleted only while it is still, byte for byte, what kit writes: anything else holds the
+// project's own lines — an edit, or a file kit merged its entries into — and kit kept no record of
+// which lines those are.
+function classify_files(files: ReadonlyArray<DistributedFile>, read_file: ReadFile): FilePlan {
+	const present = files
+		.map((file) => ({ ...file, existing: read_file(file.dest) }))
+		.filter((file) => file.existing !== undefined)
+	const untouched = new Set(
+		present.filter((file) => file.existing === file.distributed).map((file) => file.dest),
+	)
+	const destinations = [...new Set(present.map((file) => file.dest))]
+
+	return {
+		remove: destinations.filter((destination) => untouched.has(destination)),
+		keep: destinations.filter((destination) => !untouched.has(destination)),
+	}
+}
+
+function parse_manifest(manifest_text: string): Record<string, unknown> {
+	const parsed: unknown = JSON.parse(manifest_text)
+
+	if (!json_value.is_record(parsed)) throw new Error('package.json must contain an object')
+
+	return parsed
+}
+
+function without_key(record: Record<string, unknown>, key: string): Record<string, unknown> {
+	return Object.fromEntries(Object.entries(record).filter(([name]) => name !== key))
+}
+
+// The field with one key taken out of the object it holds — and the field itself once that leaves
+// the object empty, so a manifest kit created is not left carrying `"devDependencies": {}`.
+function without_nested_key(
+	manifest: Record<string, unknown>,
+	field: string,
+	key: string,
+): Record<string, unknown> {
+	const value = manifest[field]
+	if (!json_value.is_record(value) || !Object.hasOwn(value, key)) return manifest
+	const rest = without_key(value, key)
+
+	return Object.keys(rest).length === 0
+		? without_key(manifest, field)
+		: { ...manifest, [field]: rest }
+}
+
+// The manifest without kit's dependency entry and its profile record — the two entries that are
+// kit's alone, so removing them cannot take anything of the project's.
+function strip_kit(manifest_text: string): string {
+	let manifest = without_nested_key(parse_manifest(manifest_text), JOSH_FIELD, PROFILE_FIELD)
+
+	for (const field of DEPENDENCY_FIELDS) {
+		manifest = without_nested_key(manifest, field, KIT_PACKAGE_NAME)
+	}
+
+	return json_format.format_package_json(manifest)
+}
+
+// Whether the manifest still holds an entry `strip_kit` takes out — asked of the parsed manifest, so
+// a file indented another way is not mistaken for one that has something to remove.
+function has_kit_entries(manifest_text: string): boolean {
+	const unchanged = json_format.format_package_json(parse_manifest(manifest_text))
+
+	return strip_kit(manifest_text) !== unchanged
+}
+
+function shared_entries(field: string, kit_value: unknown, project_value: unknown): Array<string> {
+	if (project_value === undefined) return []
+	if (!json_value.is_record(kit_value) || !json_value.is_record(project_value)) return [field]
+
+	return Object.keys(kit_value)
+		.filter((key) => key !== KIT_PACKAGE_NAME && Object.hasOwn(project_value, key))
+		.map((key) => `${field}.${key}`)
+}
+
+// The manifest entries kit merges in that the project still holds, named `scripts.preinstall` style.
+// `kit_manifest_text` is what kit's own merge writes into an empty manifest, so the names come from
+// the merge and not from a second list of them. They are reported, never removed: the merge kept no
+// record of the value it found, so a script named `josh` may be kit's or the project's own.
+function manifest_review(manifest_text: string, kit_manifest_text: string): Array<string> {
+	const manifest = parse_manifest(manifest_text)
+
+	return Object.entries(parse_manifest(kit_manifest_text))
+		.filter(([field]) => !HANDLED_FIELDS.has(field))
+		.flatMap(([field, kit_value]) => shared_entries(field, kit_value, manifest[field]))
+}
+
+const uninstall_plan = { classify_files, strip_kit, has_kit_entries, manifest_review }
+
+export { uninstall_plan, IGNORE_FILE }
+export type { DistributedFile, FilePlan }

package/scripts/uninstall/uninstall-report.ts

@@ -0,0 +1,61 @@
+import type { FilePlan } from './uninstall-plan'
+
+interface UninstallPlan {
+	files: FilePlan
+	// Whether kit's dependency entry or profile record is still in `package.json` to take out.
+	has_manifest_entries: boolean
+	// Whether lefthook is installed here with a config kit wrote or merged into.
+	has_git_hooks: boolean
+	review: Array<string>
+}
+
+const NOTHING = '  (nothing)'
+// The review comes first: the install runs whatever `scripts.prepare` is still in the manifest, and
+// the one kit merged in installs lefthook's hooks again.
+const NEXT_STEPS = [
+	'First clear "Review by hand" — a `scripts.prepare` left there reinstalls the git hooks.',
+	'Run `pnpm install` — it drops the package from node_modules and pnpm-lock.yaml.',
+	'Delete node_modules and pnpm-lock.yaml yourself if kit was the only dependency.',
+	'Labels, Issues and pull requests `josh start` created on GitHub are not touched.',
+]
+
+function section(title: string, lines: ReadonlyArray<string>): string {
+	const body = lines.length === 0 ? [NOTHING] : lines.map((line) => `  ${line}`)
+
+	return [`${title}:`, ...body].join('\n')
+}
+
+function removal_lines(plan: UninstallPlan): Array<string> {
+	const lines = [...plan.files.remove]
+
+	if (plan.has_manifest_entries) {
+		lines.push('package.json — the @joshuafolkken/kit dependency and the josh.profile record')
+	}
+
+	if (plan.has_git_hooks) lines.push('git hooks installed by lefthook (lefthook uninstall)')
+
+	return lines
+}
+
+// Printed before anything is deleted, so the three lists are the whole of what the command will do
+// and of what it leaves for a person: nothing outside the first one is ever written to.
+function describe(plan: UninstallPlan): string {
+	return [
+		section('Remove (still exactly what kit wrote)', removal_lines(plan)),
+		section('Keep (differs from what kit writes — remove kit lines by hand)', plan.files.keep),
+		section('Review by hand (kit cannot tell these from your own)', plan.review),
+	].join('\n\n')
+}
+
+function next_steps(): string {
+	return section('Next', NEXT_STEPS)
+}
+
+function is_empty(plan: UninstallPlan): boolean {
+	return removal_lines(plan).length === 0
+}
+
+const uninstall_report = { describe, next_steps, is_empty }
+
+export { uninstall_report }
+export type { UninstallPlan }

package/scripts/uninstall/uninstall.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env tsx
+import { existsSync, readdirSync, rmdirSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { stdin as input, stdout as output } from 'node:process'
+import { createInterface } from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+import { resolve_local_bin } from '#scripts/build/local-bin'
+import { ask_yes_no_simple } from '#scripts/git/git-prompt'
+import { LEFTHOOK_PATH } from '#scripts/init/init-actions'
+import { init_logic_sonar } from '#scripts/init/init-logic-sonar'
+import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
+import { project_profile, type ProjectProfile } from '#scripts/init/project-profile'
+import { error_text } from '#scripts/lib/error-message'
+import { file_reader } from '#scripts/lib/read-file'
+import { PROJECT_CONFIG_FILE } from '#scripts/safe-chain/project-config'
+import { did_refuse_self_run } from '#scripts/self-sync-guard/self-sync-refusal'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { execaSync } from 'execa'
+import { distributed_files } from './distributed-files'
+import { IGNORE_FILE, uninstall_plan, type FilePlan } from './uninstall-plan'
+import { uninstall_report, type UninstallPlan } from './uninstall-report'
+
+const PACKAGE_JSON = 'package.json'
+const LEFTHOOK_BIN = 'lefthook'
+const ARGUMENT_START_INDEX = 2
+const YES_FLAG = '--yes'
+const UNINSTALL_USAGE = 'josh uninstall [--profile basic|full] [--yes]'
+const QUESTION = 'Remove the files and entries listed under "Remove"? (y/n): '
+const NOT_CONFIRMED = 'Nothing was removed.'
+const NO_TERMINAL = `${NOT_CONFIRMED} This is a preview: there is no terminal to confirm on, so pass --yes to remove what is listed.`
+// Written from the repository's own name and settings, so there is no distributed content to compare
+// them with: they are named for review and never deleted.
+const REVIEW_ONLY_FILES = [init_logic_sonar.get_sonar_template_destination(), PROJECT_CONFIG_FILE]
+const IGNORE_FILE_REVIEW = `${IGNORE_FILE} — delete it only once nothing it ignores (.env, node_modules) is left`
+
+interface Options {
+	is_yes: boolean
+	profile: ProjectProfile
+}
+
+function project_path(relative_path: string): string {
+	return path.join(PROJECT_ROOT, relative_path)
+}
+
+function read_project_file(relative_path: string): string | undefined {
+	return file_reader.read_if_readable(project_path(relative_path))
+}
+
+function parse_options(args: ReadonlyArray<string>): Options {
+	const rest = args.filter((argument) => argument !== YES_FLAG)
+	const requested = project_profile.requested_profile(rest, UNINSTALL_USAGE)
+
+	return {
+		is_yes: args.includes(YES_FLAG),
+		profile: project_profile.resolve_profile(PROJECT_ROOT, requested).profile,
+	}
+}
+
+// A lefthook config the profile distributes that still names the package — the one kit wrote, or the
+// project's own with kit's preset merged in. One that names it nowhere is the project's alone.
+function has_kit_lefthook_config(files: FilePlan): boolean {
+	if (![...files.remove, ...files.keep].includes(LEFTHOOK_PATH)) return false
+
+	return read_project_file(LEFTHOOK_PATH)?.includes(KIT_PACKAGE_NAME) === true
+}
+
+// Hooks are taken out only where the lefthook config is one kit wrote or merged into: once kit is
+// gone that config extends a preset that no longer exists, and a hook left in `.git/hooks` would
+// fail every commit on it.
+function has_git_hooks(files: FilePlan): boolean {
+	return (
+		has_kit_lefthook_config(files) &&
+		existsSync(project_path('.git')) &&
+		existsSync(resolve_local_bin(PROJECT_ROOT, LEFTHOOK_BIN))
+	)
+}
+
+function review_entries(manifest: string | undefined, profile: ProjectProfile): Array<string> {
+	const merged =
+		manifest === undefined
+			? []
+			: uninstall_plan.manifest_review(manifest, distributed_files.kit_manifest(profile))
+
+	return [
+		...merged.map((entry) => `${PACKAGE_JSON} ${entry}`),
+		...REVIEW_ONLY_FILES.filter((file) => existsSync(project_path(file))),
+		...(existsSync(project_path(IGNORE_FILE)) ? [IGNORE_FILE_REVIEW] : []),
+	]
+}
+
+function build_plan(profile: ProjectProfile): UninstallPlan {
+	const files = uninstall_plan.classify_files(distributed_files.list(profile), read_project_file)
+	const manifest = read_project_file(PACKAGE_JSON)
+
+	return {
+		files,
+		has_manifest_entries: manifest !== undefined && uninstall_plan.has_kit_entries(manifest),
+		has_git_hooks: has_git_hooks(files),
+		review: review_entries(manifest, profile),
+	}
+}
+
+async function is_confirmed(is_yes: boolean): Promise<boolean> {
+	if (is_yes) return true
+
+	if (!process.stdin.isTTY) {
+		console.info(`\n${NO_TERMINAL}`)
+
+		return false
+	}
+
+	const prompt = createInterface({ input, output })
+
+	try {
+		const is_accepted = await ask_yes_no_simple(prompt, `\n${QUESTION}`)
+		if (!is_accepted) console.info(NOT_CONFIRMED)
+
+		return is_accepted
+	} finally {
+		prompt.close()
+	}
+}
+
+// Run before the config is deleted, while lefthook can still read the project it is leaving.
+function remove_git_hooks(): void {
+	const bin = resolve_local_bin(PROJECT_ROOT, LEFTHOOK_BIN)
+	const result = execaSync(bin, ['uninstall'], {
+		cwd: PROJECT_ROOT,
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	if (result.exitCode === 0) console.info('  ✔ removed   git hooks')
+	else console.warn('  ⚠ lefthook uninstall failed — run it manually: lefthook uninstall')
+}
+
+function is_empty_directory(directory: string): boolean {
+	return existsSync(directory) && readdirSync(directory).length === 0
+}
+
+// A directory kit created for its own file — `.vscode`, `.github` — goes with the last file in it,
+// and one that still holds anything of the project's stays.
+function remove_empty_parents(relative_path: string): void {
+	let directory = path.dirname(relative_path)
+
+	while (directory !== '.' && is_empty_directory(project_path(directory))) {
+		rmdirSync(project_path(directory))
+		directory = path.dirname(directory)
+	}
+}
+
+function remove_file(relative_path: string): void {
+	rmSync(project_path(relative_path))
+	remove_empty_parents(relative_path)
+	console.info(`  ✔ removed   ${relative_path}`)
+}
+
+function strip_manifest(): void {
+	const manifest = read_project_file(PACKAGE_JSON)
+	if (manifest === undefined) return
+
+	writeFileSync(project_path(PACKAGE_JSON), uninstall_plan.strip_kit(manifest))
+	console.info(`  ✔ updated   ${PACKAGE_JSON}`)
+}
+
+function execute(plan: UninstallPlan): void {
+	console.info('\nRemoving:')
+	if (plan.has_git_hooks) remove_git_hooks()
+	for (const file of plan.files.remove) remove_file(file)
+	if (plan.has_manifest_entries) strip_manifest()
+	console.info(`\n${uninstall_report.next_steps()}\n\n✅ Done.\n`)
+}
+
+// The refusal `josh init` and `josh sync` make, for the opposite damage: in kit's own repository
+// every distributed file is the source, and each of them equals what kit distributes.
+async function main(args: ReadonlyArray<string> = []): Promise<void> {
+	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
+	const options = parse_options(args)
+	const plan = build_plan(options.profile)
+
+	console.info(`\n🧹 Uninstalling @joshuafolkken/kit (profile: ${options.profile})\n`)
+	console.info(uninstall_report.describe(plan))
+
+	if (uninstall_report.is_empty(plan)) {
+		console.info('\nNothing of kit is left to remove.\n')
+
+		return
+	}
+
+	if (await is_confirmed(options.is_yes)) execute(plan)
+}
+
+async function run_cli(args: ReadonlyArray<string>): Promise<void> {
+	try {
+		await main(args)
+	} catch (error) {
+		console.error(`\n✖ ${error_text.message_of(error)}\n`)
+		process.exitCode = 1
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	await run_cli(process.argv.slice(ARGUMENT_START_INDEX))
+}
+
+export { main }

package/templates/AGENTS.basic.md

@@ -0,0 +1,4 @@
+# Agent Instructions
+
+> **All rules for this project live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before doing
+> any work here, and follow every rule in it.** This file exists only to point at it.

package/templates/GEMINI.basic.md

@@ -0,0 +1,6 @@
+# Agent Instructions
+
+> **All rules for this project live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before doing
+> any work here, and follow every rule in it.** This file exists only to point at it.
+
+@CLAUDE.md

package/dist/hooks/chunk-6V5OPIUU.js

@@ -1,13 +0,0 @@
-// scripts/josh/session-language.ts
-var ENV_KEY = "JOSH_SESSION_LANG";
-var DEFAULT_SESSION_LANG = "ja";
-function resolve_session_lang() {
-  const value = process.env[ENV_KEY]?.trim();
-  if (value) return { lang: value, is_default: false };
-  return { lang: DEFAULT_SESSION_LANG, is_default: true };
-}
-var session_language = { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang };
-
-export {
-  session_language
-};

package/scripts/run/board/run-board-track.ts

@@ -1,22 +0,0 @@
-import { run_board_labels } from './run-board-labels'
-import type { Phase } from './run-board-phase'
-import type { ItemState } from './run-board-status'
-
-// A row's phases as a track: the icon of every phase it has passed, left to right, so how far a child
-// has got and what it is doing now are one mark. **The track is a history**: it grows as the child
-// goes and draws nothing ahead, since a ship that stops sends the child back and no fixed frame says
-// how many rounds are left.
-
-const { PHASE_ICONS, STATE_ICONS } = run_board_labels
-
-// A settled row's track ends on the row's own state icon rather than a fixed ✅, so a child that
-// stopped or parked never reads as having succeeded.
-function track_of(track: ReadonlyArray<Phase>, state: ItemState = 'running'): string {
-	const end = state === 'running' ? '' : STATE_ICONS[state]
-
-	return `${track.map((phase) => PHASE_ICONS[phase]).join('')}${end}`
-}
-
-const run_board_track = { track_of }
-
-export { run_board_track }