@aperant/framework 0.6.2

package/src/cli/host/detect.mjs

@@ -0,0 +1,210 @@
+/**
+ * host/detect.mjs — AI CLI host detection (C29).
+ *
+ * Detection maintenance: env-var mappings for each runtime below are the
+ * authoritative signal. They must be re-verified against each CLI's current
+ * public docs every quarter. See packages/framework/docs/intents.md
+ * §Host-detection-maintenance for the process.
+ *
+ * For env vars that could not be confirmed from public docs at the time of
+ * writing, we leave a TODO comment with the docs URL. These branches still
+ * ship — we prefer best-effort coverage + structured unknown-host error
+ * for misses over silently routing into the wrong runtime.
+ */
+
+/**
+ * Canonical list of runtime identifiers accepted by detectHost's
+ * `overrideCli` parameter AND by the route command's `--runtime <id>` flag.
+ * This list MUST stay in sync with the env-based detection branches below
+ * and with the `supported_hosts` array in the unknown-host error envelope
+ * emitted by route.mjs — the flag's whole purpose is to round-trip back to
+ * one of those identifiers when auto-detection fails.
+ */
+export const SUPPORTED_HOSTS = Object.freeze([
+	'claude-code',
+	'codex',
+	'gemini-cli',
+	'opencode',
+	'pi',
+	'cursor',
+	'windsurf',
+	'kilo',
+	'copilot',
+	'antigravity',
+	'augment',
+	'trae',
+	'qwen',
+	'cline',
+	'codebuddy',
+])
+
+/**
+ * Detect which AI CLI is currently running this script by checking environment
+ * variables set by each runtime. Returns host info and capability matrix.
+ *
+ * Detection priority (older, well-validated runtimes win over newer opt-in
+ * ones when env vars overlap): Claude Code > Codex > Gemini > OpenCode > Pi
+ * > Cursor > Windsurf > Kilo > Copilot > Antigravity > Augment > Trae > Qwen
+ * > Cline > Codebuddy > unknown.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.overrideCli] — When provided AND one of SUPPORTED_HOSTS,
+ *   the env-var detection chain is skipped and the result's `cli` is set to
+ *   this value. Capabilities are recomputed for the override (e.g. passing
+ *   'codex' when CLAUDECODE=1 is also set yields codex capabilities, not
+ *   claude-code's). Aperant-terminal detection is still environment-derived
+ *   and is NOT overridden — it describes the PTY wrapping, not the CLI host.
+ *   Invalid values are ignored (the caller should validate before calling).
+ */
+export function detectHost(opts = {}) {
+	const env = process.env
+	const { overrideCli } = opts
+
+	let cli = 'unknown'
+	let agentTeams = false
+
+	// Explicit override wins over the env-based chain. The route command
+	// validates `overrideCli` against SUPPORTED_HOSTS before calling us, so
+	// an unknown value here is a programmer error — we silently ignore it
+	// rather than throwing, since detectHost is on the hot path.
+	if (overrideCli && SUPPORTED_HOSTS.includes(overrideCli)) {
+		cli = overrideCli
+		// agent_teams is a Claude-Code-only capability tied to an env flag.
+		// When the override is claude-code, we still honor the flag so the
+		// caller gets accurate capabilities; when the override is any other
+		// runtime, agent_teams stays false regardless.
+		if (cli === 'claude-code') {
+			agentTeams = env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === '1'
+		}
+	} else if (
+		env.CLAUDECODE === '1' ||
+		env.CLAUDE_CODE_ENTRYPOINT ||
+		env.CLAUDE_CODE_SSE_PORT ||
+		env.CLAUDE_CONFIG_DIR
+	) {
+		cli = 'claude-code'
+		agentTeams = env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === '1'
+	} else if (env.CODEX_HOME || env.CODEX_THREAD_ID) {
+		cli = 'codex'
+	} else if (env.GEMINI_CONFIG_DIR || env.GEMINI_SESSION_ID) {
+		cli = 'gemini-cli'
+	} else if (env.OPENCODE_CONFIG_DIR || env.OPENCODE_CONFIG || env.OPENCODE_SESSION_ID) {
+		cli = 'opencode'
+	} else if (env.PI_CODING_AGENT === 'true') {
+		// Pi (@mariozechner/pi-coding-agent) sets PI_CODING_AGENT="true" at
+		// CLI startup — verified against v0.68.0 dist/cli.js line 9:
+		//   process.env.PI_CODING_AGENT = "true";
+		// It does NOT set PI_CONFIG_DIR or PI_SESSION_ID (those names appeared
+		// in the draft spec §9 risk #1 but proved to not actually exist —
+		// Pi only reads env vars like PI_OFFLINE / PI_TELEMETRY for user config).
+		// PI_CODING_AGENT is the single authoritative detection signal.
+		cli = 'pi'
+	} else if (env.CURSOR_TRACE_ID || env.CURSOR_CONFIG_DIR) {
+		// Cursor exposes CURSOR_TRACE_ID inside its agent/chat runtime
+		// (observed in Cursor v1.x). CURSOR_CONFIG_DIR is the canonical
+		// user-config override variable.
+		// TODO(router-0.3.0): re-verify against https://docs.cursor.com/
+		//   once the agent-API docs stabilize. Cursor's 2.x cycle may add or
+		//   rename vars; Q3-2026 maintenance sweep.
+		cli = 'cursor'
+	} else if (env.WINDSURF_CONFIG_DIR || env.WINDSURF_SESSION_ID) {
+		// Windsurf (Codeium IDE) — WINDSURF_CONFIG_DIR is the config-override
+		// variable; WINDSURF_SESSION_ID appears in the editor's agent runtime.
+		// TODO(router-0.3.0): confirm against https://docs.codeium.com/windsurf
+		//   — vars may shift as Windsurf consolidates under the Codeium
+		//   branding. Q3-2026 maintenance sweep.
+		cli = 'windsurf'
+	} else if (env.KILO_CONFIG_DIR || env.KILO_SESSION_ID) {
+		// Kilo Code CLI — config + session env vars, same shape as Codex/Gemini.
+		// TODO(router-0.3.0): confirm against https://kilocode.ai/docs once the
+		//   CLI docs surface env-var references. Q3-2026 maintenance sweep.
+		cli = 'kilo'
+	} else if (
+		env.GITHUB_COPILOT_CLI_SESSION ||
+		env.COPILOT_CLI_SESSION ||
+		env.GITHUB_COPILOT_TOKEN
+	) {
+		// GitHub Copilot CLI (gh-copilot extension). GITHUB_COPILOT_TOKEN is
+		// the auth marker; *_CLI_SESSION variants are the runtime markers
+		// observed in gh-copilot's extension process.
+		// TODO(router-0.3.0): re-verify against
+		//   https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-in-the-command-line
+		//   as Copilot's CLI surface is still evolving. Q3-2026 sweep.
+		cli = 'copilot'
+	} else if (env.ANTIGRAVITY_CONFIG_DIR || env.ANTIGRAVITY_SESSION_ID) {
+		// Google Antigravity agent runtime.
+		// TODO(router-0.3.0): verify against Antigravity's public docs once
+		//   the preview exits and runtime env-vars are documented. Q3-2026 sweep.
+		cli = 'antigravity'
+	} else if (env.AUGMENT_CONFIG_DIR || env.AUGMENT_SESSION_ID) {
+		// Augment Code agent runtime.
+		// TODO(router-0.3.0): confirm against https://www.augmentcode.com/
+		//   docs once a stable CLI surface lands. Q3-2026 sweep.
+		cli = 'augment'
+	} else if (env.TRAE_CONFIG_DIR || env.TRAE_SESSION_ID) {
+		// Trae AI IDE agent runtime.
+		// TODO(router-0.3.0): confirm against https://www.trae.ai/docs
+		//   once CLI runtime env-vars are published. Q3-2026 sweep.
+		cli = 'trae'
+	} else if (env.QWEN_CONFIG_DIR || env.QWEN_SESSION_ID) {
+		// Qwen Coder agent runtime.
+		// TODO(router-0.3.0): confirm against
+		//   https://qwenlm.github.io/ as the CLI surface evolves. Q3-2026 sweep.
+		cli = 'qwen'
+	} else if (env.CLINE_CONFIG_DIR || env.CLINE_SESSION_ID) {
+		// Cline (VSCode extension → CLI). Historically "Claude Dev"; env
+		// naming follows the current Cline branding.
+		// TODO(router-0.3.0): confirm against https://docs.cline.bot/ once
+		//   the headless CLI surface is stable. Q3-2026 sweep.
+		cli = 'cline'
+	} else if (env.CODEBUDDY_CONFIG_DIR || env.CODEBUDDY_SESSION_ID) {
+		// CodeBuddy (Tencent Cloud's code agent).
+		// TODO(router-0.3.0): confirm against CodeBuddy's public docs once
+		//   the CLI surface stabilizes. Q3-2026 sweep.
+		cli = 'codebuddy'
+	}
+
+	const isClaudeCode = cli === 'claude-code'
+	const isCodex = cli === 'codex'
+
+	// Structured prompt tools: Claude Code (AskUserQuestion), Gemini CLI (ask_user), OpenCode (question).
+	// Codex CLI has no native equivalent — falls back to numbered text prompts.
+	// Pi has dialog UI in interactive mode but no Claude-Code-style structured
+	// prompt TOOL — and the headless RPC path auto-cancels all dialogs (spec §4.3).
+	//
+	// The 10 new runtimes (cursor, windsurf, kilo, copilot, antigravity, augment,
+	// trae, qwen, cline, codebuddy) default to structured_prompts=false — none
+	// has a confirmed Claude-Code-style AskUserQuestion primitive at the time
+	// of writing. Flip to true once any of them ships one + confirm with a test.
+	const structuredPrompts = isClaudeCode || cli === 'gemini-cli' || cli === 'opencode'
+
+	// Aperant terminal detection — separate from `cli`. The framework can be
+	// running inside an Aperant-spawned PTY regardless of which CLI host
+	// (claude-code, codex, gemini-cli, opencode, pi, unknown) is at the prompt.
+	// Both env vars must be present: TERM_PROGRAM identifies the parent
+	// terminal program, APERANT_IPC_SOCKET is the absolute path to the
+	// Electron main process's Unix domain socket for nested-spawn RPC.
+	const aperantSocket = env.APERANT_IPC_SOCKET ?? null
+	const isAperantTerminal = env.TERM_PROGRAM === 'Aperant' && !!aperantSocket
+
+	const capabilities = {
+		sub_agents: isClaudeCode || isCodex,
+		agent_teams: isClaudeCode && agentTeams,
+		worktrees: isClaudeCode,
+		background_agents: isClaudeCode || isCodex,
+		structured_prompts: structuredPrompts,
+		// True when the framework can ask Electron to spawn a sibling Aperant
+		// terminal (with its own worktree + CLI) over the Unix-domain IPC socket.
+		// Requires TERM_PROGRAM=Aperant + APERANT_IPC_SOCKET to be set by the
+		// PTY launcher (NodePtyProvider + AperantIpcServer).
+		terminal_spawn: isAperantTerminal,
+	}
+
+	return {
+		cli,
+		version: null, // Version detection requires shelling out — skipped for ~50ms target
+		capabilities,
+		aperant_terminal: isAperantTerminal,
+		aperant_socket: aperantSocket,
+	}
+}

package/src/cli/host/resolve.mjs

@@ -0,0 +1,54 @@
+/**
+ * host/resolve.mjs — orchestration-mode resolver (C29).
+ */
+
+import { detectHost } from './detect.mjs'
+
+/**
+ * Resolve each orchestration preference against actual host capabilities.
+ * "auto" picks the best available; explicit modes degrade gracefully.
+ */
+export function resolveMode(requested, capabilities, fieldName) {
+	const downgradeChain = ['agent-team', 'sub-agents', 'sequential']
+
+	function bestAvailable() {
+		if (capabilities.agent_teams) return 'agent-team'
+		if (capabilities.sub_agents) return 'sub-agents'
+		return 'sequential'
+	}
+
+	if (requested === 'auto') {
+		return { resolved: bestAvailable(), downgrade: null }
+	}
+
+	// Explicit mode: check if the requested mode is available
+	if (requested === 'agent-team' && !capabilities.agent_teams) {
+		const fallback = capabilities.sub_agents ? 'sub-agents' : 'sequential'
+		return {
+			resolved: fallback,
+			downgrade: {
+				field: fieldName,
+				requested: 'agent-team',
+				resolved: fallback,
+				reason: capabilities.sub_agents
+					? `Host '${detectHost().cli}' does not support agent_teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS not set)`
+					: `Host '${detectHost().cli}' does not support agent_teams or sub_agents`,
+			},
+		}
+	}
+
+	if (requested === 'sub-agents' && !capabilities.sub_agents) {
+		return {
+			resolved: 'sequential',
+			downgrade: {
+				field: fieldName,
+				requested: 'sub-agents',
+				resolved: 'sequential',
+				reason: `Host '${detectHost().cli}' does not support sub_agents`,
+			},
+		}
+	}
+
+	// Requested mode is available
+	return { resolved: requested, downgrade: null }
+}

package/src/cli/install/archetype.mjs

@@ -0,0 +1,152 @@
+/**
+ * install/archetype.mjs — greenfield vs brownfield detection.
+ *
+ * Runs once during `apt-tools init` to pick sensible defaults + drive
+ * conditional prompts (e.g. "scan existing code now?" only makes sense
+ * on brownfield). Cheap, single-pass — no filesystem recursion.
+ *
+ * Signals we look for (positive = brownfield):
+ *   - `src/` directory exists
+ *   - `tests/` or `__tests__/` directory exists
+ *   - `package.json` exists AND has ≥1 dependency/devDependency
+ *   - `git` directory exists AND has ≥10 commits in history
+ *   - any `.ts`/`.tsx`/`.js`/`.jsx`/`.py`/`.go`/`.rs` file in the repo root
+ *
+ * Any 2 signals → brownfield. Otherwise → greenfield.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** @typedef {'greenfield' | 'brownfield'} ProjectArchetype */
+
+/**
+ * @typedef {Object} ArchetypeResult
+ * @property {ProjectArchetype} type
+ * @property {string[]} signals  Human-readable evidence lines ready for display.
+ */
+
+const CODE_EXTENSIONS = new Set([
+	'.ts',
+	'.tsx',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.py',
+	'.go',
+	'.rs',
+	'.rb',
+	'.java',
+	'.kt',
+	'.swift',
+	'.php',
+])
+
+/**
+ * Count git commits in a repo, capped for speed. Returns 0 if not a git
+ * repo or git isn't installed.
+ *
+ * @param {string} dir
+ * @returns {number}
+ */
+function countGitCommits(dir) {
+	try {
+		const out = execFileSync('git', ['-C', dir, 'rev-list', '--count', 'HEAD'], {
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+			timeout: 2000,
+		}).trim()
+		const n = Number.parseInt(out, 10)
+		return Number.isFinite(n) ? n : 0
+	} catch {
+		return 0
+	}
+}
+
+/**
+ * Whether a package.json in `dir` has at least one dependency.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function packageHasDeps(dir) {
+	const p = join(dir, 'package.json')
+	if (!existsSync(p)) return false
+	try {
+		const pkg = JSON.parse(readFileSync(p, 'utf-8'))
+		const deps = Object.keys(pkg.dependencies ?? {})
+		const devDeps = Object.keys(pkg.devDependencies ?? {})
+		return deps.length + devDeps.length > 0
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Whether the repo root contains at least one source file with a known
+ * code extension.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function hasRootCodeFile(dir) {
+	try {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			if (!entry.isFile()) continue
+			const dot = entry.name.lastIndexOf('.')
+			if (dot < 0) continue
+			if (CODE_EXTENSIONS.has(entry.name.slice(dot).toLowerCase())) return true
+		}
+	} catch {
+		// unreadable dir — treat as no signal
+	}
+	return false
+}
+
+/**
+ * Safe directory existence check.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+function dirExists(path) {
+	try {
+		return existsSync(path) && statSync(path).isDirectory()
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Detect whether the project at `dir` is greenfield (empty/new) or
+ * brownfield (existing code). The heuristic is intentionally generous:
+ * 2 positive signals flip to brownfield.
+ *
+ * @param {string} dir
+ * @returns {ArchetypeResult}
+ */
+export function detectArchetype(dir) {
+	const signals = []
+
+	if (dirExists(join(dir, 'src'))) {
+		signals.push('src/ directory exists')
+	}
+	if (dirExists(join(dir, 'tests')) || dirExists(join(dir, '__tests__'))) {
+		signals.push('existing test directory')
+	}
+	if (packageHasDeps(dir)) {
+		signals.push('package.json has dependencies')
+	}
+	const commits = countGitCommits(dir)
+	if (commits >= 10) {
+		signals.push(`git history (${commits} commits)`)
+	}
+	if (hasRootCodeFile(dir)) {
+		signals.push('source files at repo root')
+	}
+
+	const type = signals.length >= 2 ? 'brownfield' : 'greenfield'
+	return { type, signals }
+}

package/src/cli/install/atomic-text.mjs

@@ -0,0 +1,9 @@
+/**
+ * install/atomic-text.mjs — thin re-export of atomicWriteText.
+ *
+ * The canonical implementation lives in util/atomic-write.mjs alongside
+ * atomicWriteJson and appendJsonl. This shim keeps existing call-sites
+ * (pipeline.mjs and any external callers) working without change.
+ */
+
+export { atomicWriteText } from '../util/atomic-write.mjs'

package/src/cli/install/claude-hooks.mjs

@@ -0,0 +1,102 @@
+/**
+ * install/claude-hooks.mjs — generic Claude Code hook merger.
+ *
+ * Extracted from precompact-hook.mjs so PreCompact and SessionStart (and
+ * any future events) can share the same merge logic. The merge invariants:
+ *
+ *   - Read .claude/settings.local.json if it exists; if it's malformed,
+ *     return 'skipped (settings.local.json is not valid JSON)' without
+ *     clobbering user state.
+ *   - settings.hooks[event] is an array of { matcher?, hooks: [...] } groups.
+ *   - We identify our entry by a substring match against the command (e.g.
+ *     'apt-tools.mjs precompact-hook' or 'apt-check-update.js') so stale
+ *     installs get upgraded in place rather than duplicated.
+ *   - Returns one of: 'installed' | 'updated' | 'already present' | 'skipped (...)'.
+ */
+
+import { existsSync, lstatSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { atomicWriteText } from '../util/atomic-write.mjs'
+
+/**
+ * @typedef {Object} HookEntry
+ * @property {string} type     usually 'command'
+ * @property {string} command  the full shell command Claude Code will run
+ */
+
+/**
+ * @typedef {Object} HookGroup
+ * @property {string} matcher
+ * @property {HookEntry[]} hooks
+ */
+
+/**
+ * Merge a hook entry under settings.hooks[event] in
+ * .claude/settings.local.json. Returns a status string.
+ *
+ * @param {Object} args
+ * @param {string} args.projectDir
+ * @param {string} args.event           e.g. 'PreCompact', 'SessionStart'
+ * @param {string} args.command         full shell command
+ * @param {string} args.identitySubstring  substring used to find our existing entry
+ * @param {string} [args.matcher]       defaults to '*' (matches all triggers)
+ * @returns {'installed'|'updated'|'already present'|string}
+ */
+export function mergeClaudeHook({ projectDir, event, command, identitySubstring, matcher = '*' }) {
+	const claudeDir = join(projectDir, '.claude')
+	const settingsPath = join(claudeDir, 'settings.local.json')
+
+	mkdirSync(claudeDir, { recursive: true })
+
+	let settings = /** @type {Record<string, unknown>} */ ({})
+	if (existsSync(settingsPath)) {
+		try {
+			settings = JSON.parse(readFileSync(settingsPath, 'utf-8'))
+		} catch {
+			return 'skipped (settings.local.json is not valid JSON)'
+		}
+	}
+
+	if (!settings.hooks || typeof settings.hooks !== 'object') {
+		settings.hooks = {}
+	}
+	const hooks = /** @type {Record<string, unknown>} */ (settings.hooks)
+
+	const desiredEntry = /** @type {HookGroup} */ ({
+		matcher,
+		hooks: [{ type: 'command', command }],
+	})
+	const existing = Array.isArray(hooks[event]) ? /** @type {HookGroup[]} */ (hooks[event]) : []
+
+	const isOurs = (group) =>
+		Array.isArray(group?.hooks) &&
+		group.hooks.some((h) => typeof h?.command === 'string' && h.command.includes(identitySubstring))
+
+	const idx = existing.findIndex(isOurs)
+	let status
+	if (idx === -1) {
+		existing.push(desiredEntry)
+		status = 'installed'
+	} else {
+		const prev = JSON.stringify(existing[idx])
+		existing[idx] = desiredEntry
+		status = prev === JSON.stringify(desiredEntry) ? 'already present' : 'updated'
+	}
+
+	hooks[event] = existing
+
+	mkdirSync(dirname(settingsPath), { recursive: true })
+
+	// Symlink guard: refuse to follow a symlink at settingsPath to prevent
+	// overwriting arbitrary files via a hostile symlink planted at that path.
+	if (existsSync(settingsPath)) {
+		const stat = lstatSync(settingsPath)
+		if (stat.isSymbolicLink()) {
+			return 'skipped (settings.local.json is a symlink — refusing to follow)'
+		}
+	}
+
+	atomicWriteText(settingsPath, JSON.stringify(settings, null, 2) + '\n')
+
+	return status
+}

package/src/cli/install/cli-to-install-root.mjs

@@ -0,0 +1,47 @@
+/**
+ * install/cli-to-install-root.mjs — shared host-cli → install-root mapping.
+ *
+ * Extracted so both the install pipeline (which targets runtimes by their
+ * `id`) and the router (which discovers skills under the install root of
+ * whichever host CLI is detected) share a single source of truth. Keeps the
+ * scan surface and the install surface from drifting.
+ *
+ * The mapping is driven entirely by RUNTIMES[i].cliId — do not add ad-hoc
+ * aliases here. When a new runtime lands, give its descriptor a cliId and
+ * the lookups below work automatically.
+ *
+ * `null` is returned for:
+ *   - CLIs with no install target (e.g. `pi` — host detected, but no apt
+ *     install root exists for the Pi runtime).
+ *   - `'unknown'` — deterministic branches (init/status/help) don't need a
+ *     mapping; the router falls back to the framework-scoped dev default
+ *     defined in getTrustedSkillSources().
+ */
+
+import { RUNTIMES } from './runtime-detect.mjs'
+
+/**
+ * Look up the install-root (e.g. `.claude`, `.codex`, `.github/copilot`) for
+ * the runtime whose CLI is currently at the prompt.
+ *
+ * @param {string} cli  the `cli` string `detectHost()` returned
+ * @returns {string|null}  project-relative install root, or null when the
+ *   CLI has no mapped install target.
+ */
+export function cliToInstallRoot(cli) {
+	if (typeof cli !== 'string' || cli === '' || cli === 'unknown') return null
+	const runtime = RUNTIMES.find((r) => r.cliId === cli)
+	return runtime?.installRoot ?? null
+}
+
+/**
+ * Inverse lookup: for a host cli, return the full runtime descriptor. Useful
+ * for callers that need more than just the install root (e.g. markers).
+ *
+ * @param {string} cli
+ * @returns {import('./runtime-detect.mjs').RuntimeDescriptor|null}
+ */
+export function runtimeForCli(cli) {
+	if (typeof cli !== 'string' || cli === '' || cli === 'unknown') return null
+	return RUNTIMES.find((r) => r.cliId === cli) ?? null
+}