@aperant/framework 0.10.0 → 0.12.0

package/src/cli/roadmap/backend-adapter.mjs

@@ -0,0 +1,231 @@
+/**
+ * Task 26-05-26 subtask 2.4 — roadmap.backend dispatch adapter.
+ *
+ * Reads `.aperant/config.json :: roadmap.backend` and either delegates
+ * the subcommand to the Aperant Cloud MCP server (`'cloud-mcp'`) or
+ * returns a `{ delegated: false }` envelope so the calling subcommand
+ * proceeds with the existing markdown-canonical file-write path.
+ *
+ * Fast Path Guarantee: a missing `roadmap` block, a missing
+ * `roadmap.backend` key, or `backend: 'markdown'` ALL return
+ * `{ backend: 'markdown', delegated: false }` byte-identically — OSS
+ * framework users with zero cloud config see no behaviour change.
+ *
+ * Token resolution mirrors convex-mirror.mjs (token-source order ID-07):
+ *   1. process.env.MCP_ROADMAP_TOKEN
+ *   2. .aperant/team.json :: roadmapMcpToken
+ *
+ * Tool registration on the server side lands in subtask 2.3
+ * (apps/web/src/app/api/mcp/_lib/tools.ts). Until 2.3 ships, the
+ * adapter will issue the MCP call against whatever endpoint the user
+ * configured; a 404 / "unknown tool" response surfaces as a delegated
+ * error envelope rather than silently falling back to markdown.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Load `.aperant/config.json` defensively. Returns `{}` for any read
+ * or parse failure so callers never throw — the Fast Path branch must
+ * hit even when the config file is missing or malformed.
+ *
+ * @param {string} projectDir
+ * @returns {Record<string, unknown>}
+ */
+function loadConfig(projectDir) {
+	const p = join(projectDir, '.aperant', 'config.json')
+	if (!existsSync(p)) return {}
+	try {
+		const parsed = JSON.parse(readFileSync(p, 'utf-8'))
+		return parsed && typeof parsed === 'object' ? parsed : {}
+	} catch {
+		return {}
+	}
+}
+
+/**
+ * Resolve the cloud-mcp bearer token via the documented order. Returns
+ * `null` when neither source has a non-empty string.
+ *
+ * @param {string} projectDir
+ * @returns {string | null}
+ */
+function resolveToken(projectDir) {
+	const env = process.env.MCP_ROADMAP_TOKEN
+	if (typeof env === 'string' && env.length > 0) return env
+	const teamPath = join(projectDir, '.aperant', 'team.json')
+	if (!existsSync(teamPath)) return null
+	try {
+		const parsed = JSON.parse(readFileSync(teamPath, 'utf-8'))
+		if (typeof parsed.roadmapMcpToken === 'string' && parsed.roadmapMcpToken.length > 0) {
+			return parsed.roadmapMcpToken
+		}
+	} catch {
+		// Bad JSON — fall through to null
+	}
+	return null
+}
+
+/**
+ * Map a CLI subcommand to the MCP tool name registered in subtask 2.3.
+ * Read-side subcommands are intentionally absent — Phase 2 keeps reads
+ * markdown-only (cloud-mcp render is a Phase 3 follow-up per the plan).
+ *
+ * @param {string} subcommand
+ * @returns {string | null}
+ */
+function toolNameFor(subcommand) {
+	switch (subcommand) {
+		case 'add-milestone':
+			return 'roadmap.hierarchy.milestones.create'
+		case 'add-phase':
+			return 'roadmap.hierarchy.phases.create'
+		case 'set-phase-status':
+			return 'roadmap.hierarchy.phases.update'
+		case 'delete-phase':
+			return 'roadmap.hierarchy.phases.remove'
+		case 'delete-milestone':
+			return 'roadmap.hierarchy.milestones.remove'
+		default:
+			return null
+	}
+}
+
+/**
+ * Dispatch a roadmap write subcommand through the configured backend.
+ *
+ * Return shapes:
+ *   - markdown (default) → `{ backend: 'markdown', delegated: false }`
+ *     The caller proceeds with the existing markdown file-write path.
+ *   - cloud-mcp success  → `{ backend: 'cloud-mcp', delegated: true,
+ *                             result: <MCP response JSON> }`
+ *   - cloud-mcp error    → `{ backend: 'cloud-mcp', delegated: true,
+ *                             error: '<msg>', code?: <http>, status: 'error' }`
+ *
+ * The `error` branch is still `delegated: true` because the caller MUST
+ * NOT silently fall through to the markdown path when the user has
+ * opted into cloud-mcp — that would lose writes the user expected to
+ * land in Convex.
+ *
+ * @param {string} projectDir
+ * @param {string} subcommand
+ * @param {Record<string, unknown>} args
+ * @param {{ fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<
+ *   | { backend: 'markdown', delegated: false }
+ *   | { backend: 'cloud-mcp', delegated: true, result: unknown }
+ *   | { backend: 'cloud-mcp', delegated: true, status: 'error', error: string, code?: number }
+ * >}
+ */
+export async function dispatchRoadmapWrite(projectDir, subcommand, args, opts = {}) {
+	const config = loadConfig(projectDir)
+	const roadmapBlock = config.roadmap && typeof config.roadmap === 'object' ? config.roadmap : null
+	const backend =
+		roadmapBlock && typeof roadmapBlock.backend === 'string' ? roadmapBlock.backend : 'markdown'
+
+	if (backend !== 'cloud-mcp') {
+		return { backend: 'markdown', delegated: false }
+	}
+
+	const cloudMcp =
+		roadmapBlock && typeof roadmapBlock.cloudMcp === 'object' && roadmapBlock.cloudMcp !== null
+			? roadmapBlock.cloudMcp
+			: {}
+	const teamSlug = typeof cloudMcp.teamSlug === 'string' ? cloudMcp.teamSlug : null
+	if (!teamSlug || teamSlug.length === 0) {
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			error: 'roadmap.cloudMcp.teamSlug required when roadmap.backend=cloud-mcp',
+		}
+	}
+
+	const tool = toolNameFor(subcommand)
+	if (!tool) {
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			error: `cloud-mcp backend does not handle subcommand "${subcommand}" (read-side stays markdown in Phase 2)`,
+		}
+	}
+
+	const token = resolveToken(projectDir)
+	if (!token) {
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			error: 'No roadmap MCP token (set MCP_ROADMAP_TOKEN or .aperant/team.json::roadmapMcpToken)',
+		}
+	}
+
+	const baseUrl = (
+		typeof cloudMcp.mcpServerUrl === 'string' && cloudMcp.mcpServerUrl.length > 0
+			? cloudMcp.mcpServerUrl
+			: process.env.APERANT_BASE_URL || 'https://app.aperant.com'
+	).replace(/\/$/, '')
+	const url = `${baseUrl}/api/mcp/${encodeURIComponent(teamSlug)}`
+
+	// Streamable HTTP MCP body — tools/call envelope per the existing
+	// server-factory contract. The wire format mirrors what the
+	// MCP SDK clients send; the Aperant route handler dispatches on
+	// `params.name` to the matching tool registered in subtask 2.3.
+	const body = {
+		jsonrpc: '2.0',
+		id: 1,
+		method: 'tools/call',
+		params: {
+			name: tool,
+			arguments: args,
+		},
+	}
+
+	const f = opts.fetchImpl ?? fetch
+	let res
+	try {
+		res = await f(url, {
+			method: 'POST',
+			headers: {
+				Authorization: `Bearer ${token}`,
+				'Content-Type': 'application/json',
+				Accept: 'application/json, text/event-stream',
+			},
+			body: JSON.stringify(body),
+		})
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			error: `network: ${msg}`,
+		}
+	}
+
+	if (res.status >= 400) {
+		let detail = ''
+		try {
+			detail = await res.text()
+		} catch {
+			// ignore body-read failures
+		}
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			code: res.status,
+			error: detail || `http ${res.status}`,
+		}
+	}
+
+	let parsed
+	try {
+		parsed = await res.json()
+	} catch {
+		parsed = null
+	}
+	return { backend: 'cloud-mcp', delegated: true, result: parsed }
+}

package/src/cli/util/runtime-capabilities.mjs

@@ -21,6 +21,14 @@
  * whose monorepo lives elsewhere (e.g. `packages/apps/*`) pass a
  * custom `monorepo_globs`. Setting `monorepo_globs: []` disables the
  * walk entirely (root-only escape hatch).
+ *
+ * Mobile verify-proof surface — `loadRuntimeCapabilities` ALSO detects
+ * pure-native iOS/Android projects (Swift `*.xcodeproj` / Kotlin
+ * `build.gradle`) that carry no JS deps, via a shallow fs check on the
+ * root + each monorepo dir (`detectNativeProject`). The pure
+ * `detectFromPackageJson` is intentionally NOT given fs access — native
+ * detection lives ONLY in the fs-walking `loadRuntimeCapabilities` so the
+ * pure-function contract holds (decision D-06).
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
@@ -35,6 +43,10 @@ import { join, resolve } from 'node:path'
  * @property {boolean} is_web_frontend
  * @property {boolean} is_expo
  * @property {boolean} is_react_native
+ * @property {boolean} [is_ios_native]   — optional: always populated by the
+ *   detector, but optional in the type so partial capability records built by
+ *   other consumers (and pre-existing test fixtures) stay valid.
+ * @property {boolean} [is_android_native]
  * @property {boolean} has_node
  */
 
@@ -48,6 +60,8 @@ function emptyCapabilities() {
 		is_web_frontend: false,
 		is_expo: false,
 		is_react_native: false,
+		is_ios_native: false,
+		is_android_native: false,
 		has_node: false,
 	}
 }
@@ -134,6 +148,8 @@ export function loadRuntimeCapabilities(projectDir, opts) {
 			/* fall through with empty caps */
 		}
 	}
+	// Fold in pure-native detection on the root (covers a JS-less iOS/Android app).
+	rootCaps = orMergeCapabilities(rootCaps, detectNativeProject(root))
 
 	// Default to the canonical Aperant monorepo layout. Passing `[]`
 	// disables the walk entirely (root-only escape hatch per spec ID-05).
@@ -144,6 +160,9 @@ export function loadRuntimeCapabilities(projectDir, opts) {
 	for (const glob of globs) {
 		const matches = expandSimpleGlob(root, glob)
 		for (const dir of matches) {
+			// Native detection runs regardless of package.json — a pure-native
+			// iOS/Android app in apps/* may carry no package.json at all.
+			merged = orMergeCapabilities(merged, detectNativeProject(dir))
 			const childPkgPath = join(dir, 'package.json')
 			if (!existsSync(childPkgPath)) continue
 			try {
@@ -211,6 +230,54 @@ function orMergeCapabilities(a, b) {
 		is_web_frontend: a.is_web_frontend || b.is_web_frontend,
 		is_expo: a.is_expo || b.is_expo,
 		is_react_native: a.is_react_native || b.is_react_native,
+		is_ios_native: a.is_ios_native || b.is_ios_native,
+		is_android_native: a.is_android_native || b.is_android_native,
 		has_node: a.has_node || b.has_node,
 	}
 }
+
+/**
+ * Shallow fs detection of a pure-native mobile project — a Swift/ObjC iOS
+ * app (`*.xcodeproj` / `*.xcworkspace`) or a Kotlin/Java Android app
+ * (`build.gradle[.kts]` / `settings.gradle[.kts]`). Checks `dir` itself and
+ * the conventional `ios/` + `android/` subdirs (the React Native / Expo
+ * prebuild layout). Returns a full capability record so it OR-merges with
+ * the package.json-derived caps.
+ *
+ * This is the ONLY fs-touching detection — `detectFromPackageJson` stays
+ * pure (D-06). Fails closed (treats unreadable dirs as absent).
+ *
+ * @param {string} dir
+ * @returns {RuntimeCapabilities}
+ */
+function detectNativeProject(dir) {
+	const caps = emptyCapabilities()
+	if (dirHasXcodeProject(dir) || dirHasXcodeProject(join(dir, 'ios'))) {
+		caps.is_ios_native = true
+	}
+	if (dirHasGradle(dir) || dirHasGradle(join(dir, 'android'))) {
+		caps.is_android_native = true
+	}
+	return caps
+}
+
+/** True when `dir` directly contains a `*.xcodeproj` or `*.xcworkspace`. */
+function dirHasXcodeProject(dir) {
+	if (!existsSync(dir)) return false
+	try {
+		return readdirSync(dir).some((n) => n.endsWith('.xcodeproj') || n.endsWith('.xcworkspace'))
+	} catch {
+		return false
+	}
+}
+
+/** True when `dir` directly contains a Gradle build/settings file. */
+function dirHasGradle(dir) {
+	if (!existsSync(dir)) return false
+	return (
+		existsSync(join(dir, 'build.gradle')) ||
+		existsSync(join(dir, 'build.gradle.kts')) ||
+		existsSync(join(dir, 'settings.gradle')) ||
+		existsSync(join(dir, 'settings.gradle.kts'))
+	)
+}

package/src/cli/verify-proof/manifest-validator.mjs

@@ -172,6 +172,21 @@ function validateNode(value, schema, path, errors) {
 				}
 			}
 		}
+		// additionalProperties: false — reject any key not declared in `properties`.
+		if (
+			schema.additionalProperties === false &&
+			schema.properties &&
+			typeof schema.properties === 'object'
+		) {
+			for (const key of Object.keys(obj)) {
+				if (!(key in schema.properties)) {
+					errors.push({
+						path: `${path}/${key}`,
+						message: `additional property "${key}" is not allowed`,
+					})
+				}
+			}
+		}
 	}
 
 	// array validation

package/src/cli/verify-proof/resolver.mjs

@@ -124,6 +124,8 @@ function matchesRuntime(manifest, runtime) {
 		if (stripped === 'nuxt' && runtime.is_nuxt) return true
 		if (stripped === 'expo' && runtime.is_expo) return true
 		if (stripped === 'react-native' && runtime.is_react_native) return true
+		if (stripped === 'ios' && runtime.is_ios_native) return true
+		if (stripped === 'android' && runtime.is_android_native) return true
 		if (stripped === 'node' && runtime.has_node) return true
 		if (stripped === 'cli' && runtime.has_node) return true
 		if (stripped === 'api' && runtime.has_node) return true
@@ -246,12 +248,15 @@ export function resolveDriver(opts) {
  * Map a User Outcomes surface tag to the runtime-capability flag a driver
  * must carry (via `matchesRuntime`) to be eligible for that surface.
  *
- * Closed surface set: `electron | web | cli | api | electron+web`.
+ * Closed surface set: `electron | web | cli | api | mobile | electron+web`.
  * `electron+web` is NOT a single flag — it's a cross-surface tag the
- * workflow runner expands into two single-surface dispatches.
+ * workflow runner expands into two single-surface dispatches. `mobile`
+ * maps to the synthetic `is_mobile` marker, which `maskRuntimeForSurface`
+ * expands to the four real mobile flags (the unified mobile-mcp driver
+ * targets ios/android/expo/react-native — decision D-08).
  *
- * @param {('electron'|'web'|'cli'|'api')} surface
- * @returns {('is_electron'|'is_web_frontend'|'has_node')}
+ * @param {('electron'|'web'|'cli'|'api'|'mobile')} surface
+ * @returns {('is_electron'|'is_web_frontend'|'has_node'|'is_mobile')}
  */
 export function surfaceToRequiredFlag(surface) {
 	switch (surface) {
@@ -262,6 +267,8 @@ export function surfaceToRequiredFlag(surface) {
 		case 'cli':
 		case 'api':
 			return 'has_node'
+		case 'mobile':
+			return 'is_mobile'
 		default:
 			throw new Error(`surfaceToRequiredFlag: unknown surface "${surface}"`)
 	}
@@ -292,7 +299,7 @@ export function surfaceToRequiredFlag(surface) {
  * @param {Object} opts
  * @param {DriverManifest[]} opts.drivers
  * @param {RuntimeCapabilities} opts.runtime
- * @param {Array<{id: string, surface: 'electron'|'web'|'cli'|'api'|'electron+web'}>} opts.outcomes
+ * @param {Array<{id: string, surface: 'electron'|'web'|'cli'|'api'|'mobile'|'electron+web'}>} opts.outcomes
  * @param {string[]} [opts.override]
  * @param {string[]} [opts.required_stability]
  * @param {string[]} [opts.required_capabilities] — defaults to ['screenshot']
@@ -314,7 +321,9 @@ export function resolveDriversForOutcomes(opts) {
 			outcome.surface === 'electron+web' ? ['electron', 'web'] : [outcome.surface]
 
 		for (const surface of surfacesToDispatch) {
-			const flag = surfaceToRequiredFlag(/** @type {'electron'|'web'|'cli'|'api'} */ (surface))
+			const flag = surfaceToRequiredFlag(
+				/** @type {'electron'|'web'|'cli'|'api'|'mobile'} */ (surface),
+			)
 			// Synthesize a per-surface runtime view: only the surface's
 			// required flag is on; every other flag is masked off so the
 			// scoring prefers per-surface drivers (otherwise, on a
@@ -347,7 +356,7 @@ export function resolveDriversForOutcomes(opts) {
  * single surface during per-outcome dispatch.
  *
  * @param {RuntimeCapabilities} runtime
- * @param {string} flag — one of: is_electron | is_web_frontend | has_node
+ * @param {string} flag — one of: is_electron | is_web_frontend | has_node | is_mobile
  * @returns {RuntimeCapabilities}
  */
 function maskRuntimeForSurface(runtime, flag) {
@@ -360,6 +369,8 @@ function maskRuntimeForSurface(runtime, flag) {
 		is_web_frontend: false,
 		is_expo: false,
 		is_react_native: false,
+		is_ios_native: false,
+		is_android_native: false,
 		has_node: false,
 	}
 	// Only flip the surface's flag on if the project actually carries it
@@ -373,5 +384,14 @@ function maskRuntimeForSurface(runtime, flag) {
 		masked.is_nuxt = runtime.is_nuxt
 	}
 	if (flag === 'has_node') masked.has_node = runtime.has_node
+	// `is_mobile` is a synthetic surface marker — expand it to the four real
+	// mobile flags so the unified mobile-mcp driver (targets ios/android/
+	// expo/react-native) matches whichever the project actually carries.
+	if (flag === 'is_mobile') {
+		masked.is_ios_native = runtime.is_ios_native
+		masked.is_android_native = runtime.is_android_native
+		masked.is_expo = runtime.is_expo
+		masked.is_react_native = runtime.is_react_native
+	}
 	return masked
 }