@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/josh/josh-usage-developer.ts

@@ -1,230 +0,0 @@
-import { ports } from '#ports'
-import type { CommandUsage } from './josh-command-types'
-
-// The usage of the commands `docs/josh-commands.md` documents, keyed by command name. The page's
-// usage blocks are generated from this table and `josh help <command>` prints it, so an example or a
-// flag is written once, here (#3932).
-// The unseeded ports are read from `ports/index.js`, their one definition (#818).
-const UNSEEDED: Readonly<Record<string, string | undefined>> = {}
-const NARROWED = { arguments: 'scripts/thing.ts', note: 'narrow by the given files instead' }
-
-/* eslint-disable @typescript-eslint/naming-convention */
-const DEVELOPER_USAGE: Readonly<Record<string, CommandUsage>> = {
-	gate: {
-		examples: [
-			{ arguments: '' },
-			{ arguments: '--verbose', note: "every check's output, passing ones included" },
-			{ arguments: '--force', note: 're-run even on a tree already recorded green' },
-			{ arguments: '--no-unit', note: 'the static checks only (CI only)' },
-		],
-	},
-	lint: { examples: [{ arguments: '' }] },
-	'lint:related': { examples: [{ arguments: '' }, NARROWED] },
-	lines: {
-		examples: [{ arguments: 'scripts/hooks/format-edited-file.ts scripts/josh/josh-logic.ts' }],
-	},
-	bytes: {
-		examples: [
-			{ arguments: 'docs/josh-commands.md', note: 'one document' },
-			{ arguments: '', note: 'scan: every budgeted document near its ceiling' },
-		],
-	},
-	metrics: {
-		examples: [
-			{ arguments: '', note: "print the totals and check them against the merge-base's" },
-			{ arguments: '--accept --reason "<why>"', note: "record this branch's growth and why" },
-		],
-	},
-	format: { examples: [{ arguments: '' }] },
-	'cspell:dot': { examples: [{ arguments: '', note: 'includes dotfiles' }] },
-	behavior: { examples: [{ arguments: '' }] },
-	'exports:unused': { examples: [{ arguments: '' }] },
-	'test:unit': { examples: [{ arguments: '' }] },
-	'test:related': {
-		examples: [
-			{ arguments: '' },
-			NARROWED,
-			{ arguments: '--silent', note: 'flags are forwarded to vitest' },
-		],
-	},
-	'test:declared': {
-		examples: [
-			{ arguments: '' },
-			{ arguments: '--match', note: 'check Step 0 declarations on stdin' },
-			{ arguments: '--help', note: 'print usage, including the --match stdin form' },
-		],
-	},
-	'test:e2e': { examples: [{ arguments: '' }] },
-	test: { examples: [{ arguments: '' }] },
-	check: { examples: [{ arguments: '' }] },
-	port: {
-		examples: [
-			{
-				arguments: 'dev',
-				note: `${String(ports.resolve_development_port(UNSEEDED))} with no seed set`,
-			},
-			{
-				arguments: 'preview',
-				note: `${String(ports.resolve_preview_port(UNSEEDED))} with no seed set`,
-			},
-		],
-	},
-	profile: { examples: [{ arguments: '' }] },
-	init: {
-		examples: [
-			{
-				arguments: '',
-				note: 'create/merge config files, install and format (--no-install skips both, --dry-run only prints the plan)',
-			},
-		],
-	},
-	'registry:migrate': { examples: [{ arguments: '' }] },
-	sync: { examples: [{ arguments: '', note: 'overwrite managed files' }] },
-	uninstall: {
-		examples: [
-			{ arguments: '', note: 'show the plan, then ask' },
-			{ arguments: '--yes', note: 'remove without asking' },
-		],
-	},
-	adopt: {
-		examples: [
-			{ arguments: '' },
-			{ arguments: '--dry-run', note: 'report the steps without touching anything' },
-		],
-		flags: [{ names: ['--dry-run'], description: 'report the plan without writing.' }],
-	},
-	git: {
-		examples: [
-			{ arguments: '', note: 'interactive' },
-			{ arguments: '-y', note: 'unattended (no TTY required)' },
-			{ arguments: '-y "title"', note: 'set commit message prefix' },
-			{ arguments: '-y "<title> #<N>"', note: 'follow-up commit on the same branch' },
-			{
-				arguments: '-y --skip-commit --skip-push',
-				note: 'open the PR without committing/pushing',
-			},
-		],
-		flags: [
-			{
-				names: ['-y', '--yes'],
-				description: 'run non-interactively; works without a TTY (agent or CI shell).',
-			},
-			{
-				names: ['--skip-commit', '--skip-push'],
-				description: 'recover/open a PR without a new commit or push.',
-			},
-		],
-	},
-	pr: { examples: [{ arguments: '', note: 'open the PR for the current <N>-<slug> branch' }] },
-	'review:findings': { examples: [{ arguments: '' }] },
-	'main:sync': { examples: [{ arguments: '' }] },
-	'main:merge': { examples: [{ arguments: '' }] },
-	version: {
-		examples: [
-			{ arguments: '' },
-			{
-				arguments: '--upgrade',
-				note: 'upgrade global + project to latest, then re-run fix-gh-packages',
-			},
-		],
-		flags: [
-			{
-				names: ['--upgrade'],
-				description:
-					'upgrade both the global install (`pnpm add -g`) and the project devDependency (`pnpm add -D` + `fix-gh-packages`); already-current or not-installed targets are skipped.',
-			},
-		],
-	},
-	ranges: { examples: [{ arguments: '' }] },
-	doctor: {
-		examples: [
-			{ arguments: '', note: 'diagnose only' },
-			{ arguments: '--fix', note: 'reclaim the global josh by removing a stale kit shim' },
-			{ arguments: '--ports', note: 'also print the per-repository port-seed table' },
-		],
-		flags: [
-			{
-				names: ['--fix'],
-				description:
-					'remove a shadowing binary **only if it is a kit shim** (its body references `@joshuafolkken/kit` or the removed `install-bin` script); any other binary is left and reported for manual review. Also the one-shot recovery for an old project that re-created the global shim.',
-			},
-			{ names: ['--ports'], description: 'additionally print the port-seed table (see below).' },
-		],
-	},
-	audit: { examples: [{ arguments: '' }] },
-	overrides: {
-		examples: [
-			{ arguments: '', note: 'verify overrides unchanged' },
-			{ arguments: '--save', note: 'snapshot current merged overrides' },
-		],
-		flags: [
-			{
-				names: ['--save'],
-				description:
-					'write the current merged overrides to `.overrides-snapshot.json` (gitignored); later runs compare against it and exit non-zero on any add, removal, or change.',
-			},
-		],
-	},
-	backlogrun: {
-		examples: [
-			{ arguments: '', note: 'start in Claude, then show the board' },
-			{ arguments: '3437 --only', note: 'the arguments go to backlogrun as typed' },
-			{ arguments: '--agent codex', note: 'start in Codex' },
-			{ arguments: '--stop', note: 'stop the run in this repository' },
-		],
-	},
-	'lane:limit': {
-		examples: [
-			{ arguments: '8', note: "raise or lower the live run's limit to 8" },
-			{ arguments: '', note: 'print the limit, the lanes in use and the free lanes' },
-			{ arguments: '--reset', note: 'clear the override; JOSH_LANE_LIMIT applies again' },
-		],
-	},
-	'lane:withdraw': {
-		examples: [{ arguments: '3769 --reason "folded into a broader issue"' }],
-	},
-	'test:red': { examples: [{ arguments: '', note: 'red, green, no-test or test-only' }] },
-	start: {
-		examples: [
-			{ arguments: '', note: 'asks for the profile and the repository' },
-			{
-				arguments: '--yes --github --profile basic',
-				note: 'unattended, including the GitHub repository',
-			},
-		],
-		flags: [
-			{ names: ['--profile basic|full'], description: 'the profile, without asking.' },
-			{ names: ['--yes'], description: 'take the defaults — not consent to write to GitHub.' },
-			{ names: ['--github'], description: 'create the GitHub repository and push `main`.' },
-			{ names: ['--public'], description: 'create the repository public instead of private.' },
-			{
-				names: ['--init-command "<command>"'],
-				description: 'run this setup command in place of `josh init`.',
-			},
-			{
-				names: ['--push-preflight-command "<command>"'],
-				description:
-					'a check run before the first step when the plan pushes; a failure stops the run before it writes anything.',
-			},
-			{ names: ['--dry-run'], description: 'print the plan and change nothing.' },
-		],
-	},
-	latest: { examples: [{ arguments: '', note: 'full update (update + audit + pnpm)' }] },
-	'latest:corepack': { examples: [{ arguments: '', note: 'update pnpm only' }] },
-	'latest:update': { examples: [{ arguments: '', note: 'update dependencies only' }] },
-	'lane:restart': {
-		examples: [{ arguments: '3769', note: "prints the fresh child's pid" }],
-	},
-	'rule:value': {
-		examples: [
-			{ arguments: '' },
-			{
-				arguments: '--refresh',
-				note: 'write the reading to the loop-head cache instead of stdout',
-			},
-		],
-	},
-}
-/* eslint-enable @typescript-eslint/naming-convention */
-
-export { DEVELOPER_USAGE }

package/scripts/josh/josh-usage-hooks.ts

@@ -1,38 +0,0 @@
-import type { CommandUsage } from './josh-command-types'
-
-// The usage of the Claude Code and Codex hook commands `docs/josh-commands-automation.md` documents
-// under "Development", keyed by command name. A hook is fed its payload as JSON on stdin, so each
-// example names the event that runs it rather than an argument. The page's usage blocks are generated
-// from this table and `josh help <command>` prints it, so an example is written once, here (#3981).
-const PRE_TOOL_USE = 'run by the PreToolUse hook, the pending tool call as JSON on stdin'
-const IN_PRETOOL_GUARD = 'run inside pretool:guard, not wired on its own'
-
-/* eslint-disable @typescript-eslint/naming-convention */
-const HOOK_USAGE: Readonly<Record<string, CommandUsage>> = {
-	'format:edited': {
-		examples: [
-			{ arguments: '', note: 'run by the PostToolUse hook, the tool call as JSON on stdin' },
-		],
-	},
-	'batch:guard': { examples: [{ arguments: '', note: IN_PRETOOL_GUARD }] },
-	'investigation:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
-	'duplicate-read:guard': { examples: [{ arguments: '', note: IN_PRETOOL_GUARD }] },
-	'rule:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
-	'rule:list': { examples: [{ arguments: '', note: 'print every trigger-delivered rule' }] },
-	'pretool:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
-	'codex:hook-adapter': {
-		examples: [
-			{ arguments: 'pretool', note: 'a Codex PreToolUse payload on stdin' },
-			{ arguments: 'posttool', note: 'a Codex PostToolUse payload on stdin' },
-		],
-	},
-	'stop:guard': {
-		examples: [{ arguments: '', note: 'run by the Stop hook, the stop payload as JSON on stdin' }],
-	},
-	'session:lang': {
-		examples: [{ arguments: '', note: 'run by the UserPromptSubmit hook; `ja` prints nothing' }],
-	},
-}
-/* eslint-enable @typescript-eslint/naming-convention */
-
-export { HOOK_USAGE }

package/scripts/josh/josh-usage-issue.ts

@@ -1,205 +0,0 @@
-import type { CommandUsage } from './josh-command-types'
-
-// The usage of the issue commands `docs/josh-commands-backlog.md` documents under "Issues", keyed by
-// command name. The page's usage blocks are generated from this table and `josh help <command>`
-// prints it, so an example or a flag is written once, here (#3938). The epic and backlog commands are
-// `josh-usage-backlog.ts`, the review and delegation commands `josh-usage-review.ts`.
-const REPO = '--repo <owner/repo>'
-const BODY_FILE = '--body-file <path>'
-const CONCURRENT = 'several numbers, read concurrently'
-const REPO_FLAG = {
-	names: [REPO],
-	description: 'read a child in another repository; applies to every number.',
-}
-const JSON_FLAG = { names: ['--json'], description: 'print the verdict and reason as JSON.' }
-
-/* eslint-disable @typescript-eslint/naming-convention */
-const ISSUE_USAGE: Readonly<Record<string, CommandUsage>> = {
-	'issue:read': {
-		examples: [{ arguments: '1715' }, { arguments: '1715 1567 1605', note: CONCURRENT }],
-	},
-	'issue:ack': { examples: [{ arguments: '3773' }] },
-	'issue:state': {
-		examples: [
-			{ arguments: '42', note: 'single-number shape' },
-			{ arguments: '42 43 44', note: 'each block headed by `issue:`' },
-			{ arguments: '42 43 --repo joshuafolkken/app-kit', note: 'a child in another repo' },
-		],
-		flags: [REPO_FLAG],
-	},
-	'issue:release': {
-		examples: [
-			{ arguments: '3360' },
-			{ arguments: '3716 --wait', note: 'blocked by the release issue instead' },
-		],
-		flags: [
-			{
-				names: ['--wait'],
-				description:
-					'the issue is blocked by the release issue instead, so `backlog:next` offers it again once the release ships (`.claude/skills/workflow-commands/prerequisite.md`).',
-			},
-		],
-	},
-	'issue:scout': {
-		examples: [
-			{ arguments: '"Stop the gate re-running after every edit"' },
-			{ arguments: '"<title>" --body "parent: #1246"' },
-			{ arguments: '"<title>" --body-file draft.md' },
-		],
-		flags: [
-			{
-				names: ['--body "<text>"'],
-				description:
-					'supply references (`#N`) in a `parent: #N` line or an acceptance-criteria section so the epic half has a number to work from; without one there (a background mention does not count) it prints `Epic: not asked`.',
-			},
-			{
-				names: [BODY_FILE],
-				description:
-					'pass the whole draft, including its purpose, requirements and acceptance criteria. A file that cannot be read ends the command rather than being treated as "no candidates".',
-			},
-		],
-	},
-	'issue:file': {
-		examples: [
-			{ arguments: '"<title>" --body-file body.md --depth 1' },
-			{
-				arguments:
-					'"<title>" --body-file body.md --depth 0 --route tier-a --repo joshuafolkken/kit',
-			},
-			{ arguments: '"<title>" --body-file body.md --depth 1 --distinct 2801,2795' },
-		],
-		flags: [
-			{ names: [BODY_FILE], description: 'the body. Required.' },
-			{
-				names: ['--depth <0|1|2>'],
-				description:
-					'the depth label. Required. The criteria are `.claude/skills/workflow-commands/observation-filing.md` → "The depth test".',
-			},
-			{
-				names: ['--route <tier-a|split|interrupt|review-cap>'],
-				description:
-					'the `route:` label naming the filing route. Omit it for a filing with no route.',
-			},
-			{
-				names: ['--label <name>'],
-				description: 'an extra label (for example `epic`). Repeatable.',
-			},
-			{
-				names: [REPO],
-				description: 'the target repository. Defaults to this repository.',
-			},
-			{
-				names: ['--distinct <N,…>'],
-				description: 'duplicate candidates you read and judged distinct.',
-			},
-			{
-				names: ['--over-cap'],
-				description: 'the run is blocked by this filing; the cap lets it through.',
-			},
-			{
-				names: ['--no-auto-ok'],
-				description: "needs a person's judgement (Tier B / C); no `auto-ok`.",
-			},
-			{
-				names: ['--release'],
-				description:
-					"a consumer can use the change only once it is published. The filed issue becomes a blocker of the target's release issue (step 10).",
-			},
-		],
-	},
-	'issue:fold-existing': { examples: [{ arguments: 'assessment.json --json' }] },
-	'issue:fold': {
-		examples: [
-			{
-				arguments: '"First finding" "Second finding"',
-				note: 'fold | separate | no-fold-needed | undetermined',
-			},
-			{ arguments: '"a" "b" --not-separable', note: 'the pair is really one deliverable → fold' },
-			{ arguments: '"a" "b" --json', note: 'the verdict and reason, machine-readable' },
-		],
-		flags: [
-			{
-				names: ['--not-separable'],
-				description:
-					'declare the judgement half: the findings are one deliverable, so they fold whatever their size.',
-			},
-			JSON_FLAG,
-		],
-	},
-	'issue:cite': {
-		examples: [
-			{ arguments: '2220' },
-			{ arguments: '2220 1758 1252', note: CONCURRENT },
-			{ arguments: '45 --repo joshuafolkken/app-kit', note: 'bare numbers in another repository' },
-			{ arguments: 'joshuafolkken/app-kit#45 2220', note: 'per-token owner/repo#N notation' },
-		],
-		flags: [
-			{
-				names: [REPO],
-				description:
-					'the repository for every bare number; a token written `owner/repo#N` overrides it for itself.',
-			},
-		],
-	},
-	'issue:comment': {
-		examples: [
-			{
-				arguments: '2304 --body-file .claude/tmp/park.md',
-				note: 'the body from a file — no shell evaluates it',
-			},
-			{
-				arguments: '2304 --body "a short note"',
-				note: 'inline, for a body with no backticks or $',
-			},
-		],
-		flags: [
-			{
-				names: ['--body <text>'],
-				description: 'the comment body, inline. Trimmed, with `\\n` expanded to a newline.',
-			},
-			{
-				names: [BODY_FILE],
-				description:
-					'read the body from a file, or from stdin with `-`. The safe form the rule steers every caller toward.',
-			},
-		],
-	},
-	'pkg:scout': {
-		examples: [{ arguments: '"date formatting" --size 5' }],
-		flags: [
-			{ names: ['--size <n>'], description: 'how many candidates to fetch and rank (default 10).' },
-		],
-	},
-	'issue:lint': { examples: [{ arguments: '.claude/tmp/issue-body.md' }] },
-	'defect:rate': {
-		examples: [{ arguments: '', note: 'the last 14 days' }, { arguments: '--days 30' }],
-		flags: [
-			{
-				names: ['--days <n>'],
-				description:
-					'the window in whole days (default 14, at most 3650). Anything else prints the usage and exits 1.',
-			},
-		],
-	},
-	'issue:backlinks': { examples: [{ arguments: '2123' }] },
-	'report:lint': { examples: [{ arguments: '< summary.md' }] },
-	'stash:pop': {
-		examples: [
-			{ arguments: '"backlogrun: parked #2028"' },
-			{
-				arguments: '"backlogrun: josh latest before lanes" --dir "$dir"',
-				note: "into a lane's work tree",
-			},
-		],
-		flags: [
-			{
-				names: ['--dir <path>'],
-				description:
-					'applies the pop in that work tree (`git -C <path>`); without it the pop lands in the current checkout. The stack is shared, so it reads the same either way.',
-			},
-		],
-	},
-}
-/* eslint-enable @typescript-eslint/naming-convention */
-
-export { ISSUE_USAGE }

package/scripts/josh/josh-usage-review.ts

@@ -1,101 +0,0 @@
-import type { CommandUsage } from './josh-command-types'
-
-// The usage of the review, delegation and oracle commands `docs/josh-commands-backlog.md` documents
-// under "Review, delegation and oracles", keyed by command name. The page's usage blocks are generated
-// from this table and `josh help <command>` prints it, so an example or a flag is written once, here
-// (#3938).
-const MACHINE_READABLE = 'the verdict and the reason, machine-readable'
-const LEVEL_ONLY = '--level-only'
-const JSON_FLAG = '--json'
-const CHECK = '--check'
-const ROUND_1_CLOSED = '--round-1-closed'
-
-/* eslint-disable @typescript-eslint/naming-convention */
-const REVIEW_USAGE: Readonly<Record<string, CommandUsage>> = {
-	'review:brief': {
-		examples: [
-			{ arguments: '', note: 'round 1' },
-			{ arguments: '--round 2', note: 'verification pass, scoped to the fix delta' },
-			{ arguments: LEVEL_ONLY, note: 'the level alone (pre-commit review)' },
-			{ arguments: '--level-only --json', note: 'level and reason, machine-readable' },
-		],
-		flags: [
-			{
-				names: ['--round 2'],
-				description:
-					"target is round 1's fixes and nothing else (widened back to the whole change when the record's change base no longer matches).",
-			},
-			{
-				names: [LEVEL_ONLY],
-				description:
-					'print the level alone (level to stdout, reason to stderr); bypasses the scoped-green refusal.',
-			},
-			{
-				names: ['--staged', '--json'],
-				description: 'the staged diff; machine-readable level and reason.',
-			},
-		],
-	},
-	'review:round2': {
-		examples: [
-			{ arguments: '', note: '→ required' },
-			{ arguments: ROUND_1_CLOSED, note: '→ required | skip' },
-			{ arguments: JSON_FLAG, note: MACHINE_READABLE },
-		],
-		flags: [
-			{
-				names: [ROUND_1_CLOSED],
-				description:
-					'the caller states every round-1 High/Medium finding closed and none was filed or deferred; its absence answers `required`.',
-			},
-			{ names: [JSON_FLAG], description: 'machine-readable verdict and reason.' },
-		],
-	},
-	disposition: { examples: [{ arguments: '<path...>', note: '→ runtime | non-runtime' }] },
-	'review:attest': {
-		examples: [
-			{ arguments: '<nonce>', note: 'run by the review, from the checkout it read' },
-			{ arguments: CHECK, note: 'run by the run, before it acts on the review' },
-		],
-		flags: [
-			{ names: ['<nonce>'], description: 'attest the checkout the review read.' },
-			{
-				names: [CHECK],
-				description: 'verify before acting; `josh followup` asks again before merging.',
-			},
-		],
-	},
-	delegate: {
-		examples: [
-			{ arguments: 'gate-fix', note: '→ delegate' },
-			{ arguments: 'review', note: '→ keep' },
-			{ arguments: '--list', note: 'the enumeration, and what was rejected and why' },
-		],
-	},
-	fanout: {
-		examples: [
-			{ arguments: 'scripts/a.ts,scripts/a.test.ts scripts/b.ts', note: '→ parallel' },
-			{
-				arguments: 'scripts/a.ts,shared.ts scripts/b.ts,shared.ts',
-				note: '→ serial (units share shared.ts)',
-			},
-			{ arguments: 'scripts/a.ts', note: '→ serial (fewer than two units)' },
-		],
-	},
-	'split:assess': {
-		examples: [
-			{ arguments: '', note: '→ single' },
-			{ arguments: JSON_FLAG, note: MACHINE_READABLE },
-		],
-	},
-	'oracle:list': { examples: [{ arguments: '' }] },
-	'clone:scan': { examples: [{ arguments: '' }] },
-	cases: {
-		examples: [
-			{ arguments: 'scripts/a.ts scripts/b.ts', note: 'the boundaries these paths cross' },
-		],
-	},
-}
-/* eslint-enable @typescript-eslint/naming-convention */
-
-export { REVIEW_USAGE }