@nifrajs/cli 0.1.0-alpha.1

package/src/openapi-tool.ts

@@ -0,0 +1,51 @@
+import { basename } from "node:path"
+import { toOpenAPI } from "@nifrajs/schema/openapi"
+import type { LoadedApp } from "./load.ts"
+
+export type OpenApiFormat = "json" | "yaml"
+
+function hasRoutesMethod(value: unknown): value is Parameters<typeof toOpenAPI>[0] {
+  return typeof (value as { routes?: unknown } | undefined)?.routes === "function"
+}
+
+function indent(text: string, spaces: number): string {
+  const pad = " ".repeat(spaces)
+  return text
+    .split("\n")
+    .map((line) => (line.length === 0 ? line : `${pad}${line}`))
+    .join("\n")
+}
+
+function toYaml(value: unknown, depth = 0): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value)
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]"
+    return value
+      .map((item) => {
+        if (item !== null && typeof item === "object")
+          return `-\n${indent(toYaml(item, depth + 1), 2)}`
+        return `- ${toYaml(item, depth + 1)}`
+      })
+      .join("\n")
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+  if (entries.length === 0) return "{}"
+  return entries
+    .map(([key, item]) => {
+      const rendered = toYaml(item, depth + 1)
+      if (item !== null && typeof item === "object" && rendered !== "{}" && rendered !== "[]") {
+        return `${JSON.stringify(key)}:\n${indent(rendered, 2)}`
+      }
+      return `${JSON.stringify(key)}: ${rendered}`
+    })
+    .join("\n")
+}
+
+/** Render a project's backend as OpenAPI 3.1. Frontend-only apps get a valid empty document, which is
+ * easier for agents and API tooling to handle than a tool error. */
+export function renderOpenApi(app: LoadedApp, format: OpenApiFormat): string {
+  const title = `${basename(app.cwd)} API`
+  const input = hasRoutesMethod(app.backend) ? app.backend : {}
+  const document = toOpenAPI(input, { title, version: "1.0.0" })
+  return format === "yaml" ? toYaml(document) : JSON.stringify(document, null, 2)
+}

package/src/scaffold.ts

@@ -0,0 +1,164 @@
+/**
+ * `nifra_scaffold` — turn a URL path into the correct `routes/` file (the convention an agent most often
+ * gets wrong) + a minimal, contract-correct stub. The mapping is the inverse of @nifrajs/web's
+ * `filePathToPatterns`: `:id`/`[id]` → `[id]`, `*rest`/`[...rest]` → `[...rest]`, `[[lang]]` optional,
+ * `/` → `index`. The framework (→ file extension) comes from the project's `clientModule`.
+ *
+ * Page stubs are emitted only for the JSX family (react/preact/solid — one shared, verified shape);
+ * for vue/svelte/vanilla we return the correct PATH + the route-module contract and point at
+ * `nifra_example` for the body, rather than hand-writing an SFC we can't typecheck here.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises"
+import { dirname, resolve, sep } from "node:path"
+
+export type Framework = "react" | "preact" | "solid" | "vue" | "svelte" | "vanilla"
+
+const EXT: Record<Framework, string> = {
+  react: "tsx",
+  preact: "tsx",
+  solid: "tsx",
+  vue: "vue",
+  svelte: "svelte",
+  vanilla: "ts",
+}
+
+/** Derive the framework from a `clientModule` like `@nifrajs/web-react/client`. Defaults to react. */
+export function frameworkFromClientModule(clientModule: string | undefined): Framework {
+  const m = /@nifrajs\/web-(react|preact|solid|vue|svelte|vanilla)\b/.exec(clientModule ?? "")
+  return (m?.[1] as Framework | undefined) ?? "react"
+}
+
+/** One URL path segment → its `routes/` filename segment. Accepts both URL (`:id`, `*rest`) and
+ * file (`[id]`, `[...rest]`) spellings so an agent can pass either. */
+function segmentToFile(seg: string): string {
+  if (seg.startsWith("[")) return seg // already file-spelled ([id], [...rest], [[lang]])
+  if (seg.startsWith("*")) return `[...${seg.slice(1) || "rest"}]` // *rest / * → catch-all
+  if (seg.startsWith(":")) return `[${seg.slice(1)}]` // :id → [id]
+  return seg
+}
+
+/** Map a URL path to its `routes/` file path (relative to `routes/`, without extension prefix dir).
+ * `/` → `index`; `/users/:id` → `users/[id]`; `/blog/*slug` → `blog/[...slug]`. */
+export function routePathToFile(urlPath: string, ext: string): string {
+  const segments = urlPath.split("/").filter((s) => s.length > 0)
+  if (segments.length === 0) return `routes/index.${ext}`
+  const last = segments.length - 1
+  // Catch-all must be the final segment (mirrors @nifrajs/web); flag it rather than emit an invalid file.
+  for (let i = 0; i < last; i++) {
+    if (segments[i]?.startsWith("*") || segments[i]?.startsWith("[..."))
+      throw new Error(`catch-all must be the last segment: "${urlPath}"`)
+  }
+  return `routes/${segments.map(segmentToFile).join("/")}.${ext}`
+}
+
+const ROUTE_CONTRACT = `A route module may export:
+- \`export default function Page(props: { data: LoaderData<typeof loader> }) { … }\` — the page component.
+- \`export async function loader({ params, request, api }: LoaderArgs<typeof backend>) { … }\` — server-only; data for SSR. Reach the backend via \`api\` (typed) / DB via the backend, NEVER a top-level server-only import.
+- \`export async function action({ request, api }: ActionArgs<typeof backend>) { … }\` — server-only; handles the form POST.
+- \`export const meta = { title, meta:[…] }\` — head tags.
+Path params are typed on \`params\`.`
+
+function jsxStub(file: string, params: string[]): string {
+  const paramsNote =
+    params.length > 0 ? `params.${params.join(", params.")}` : "no path params on this route"
+  const loaderLine =
+    params.length > 0
+      ? `// export async function loader({ params, api }: LoaderArgs<typeof backend>) { return { /* fetch by ${params[0]} */ } }`
+      : `// export async function loader({ api }: LoaderArgs<typeof backend>) { return {} }`
+  return `// ${file} — server-only loader/action allowed; never top-level-import server-only code (DB/secrets).
+// Available here: ${paramsNote}. Fetch data in a loader via the typed \`api\`; see nifra_example("loader").
+${loaderLine}
+export default function Page() {
+  return <main>TODO: ${file}</main>
+}
+`
+}
+
+/** Param names a route file declares, for the stub's notes. */
+function paramsOf(file: string): string[] {
+  const out: string[] = []
+  for (const m of file.matchAll(/\[(?:\.\.\.)?([A-Za-z_][A-Za-z0-9_]*)\]/g))
+    out.push(m[1] as string)
+  return out
+}
+
+export interface ScaffoldResult {
+  readonly file: string
+  readonly content?: string
+  readonly note: string
+}
+
+export interface ScaffoldWriteResult extends ScaffoldResult {
+  readonly written: boolean
+  readonly reason?: string
+}
+
+/** Scaffold a page route for `urlPath` under the project's `framework`. Returns the correct file path
+ * always; a ready-to-write stub for the JSX family, contract guidance otherwise. */
+export function scaffoldRoute(urlPath: string, framework: Framework): ScaffoldResult {
+  const ext = EXT[framework]
+  const file = routePathToFile(urlPath, ext)
+  const params = paramsOf(file)
+  if (framework === "react" || framework === "preact" || framework === "solid") {
+    return {
+      file,
+      content: jsxStub(file, params),
+      note: `Create ${file}. ${ROUTE_CONTRACT}`,
+    }
+  }
+  return {
+    file,
+    note: `Create ${file} as a ${framework} route module. ${ROUTE_CONTRACT}\nFor the ${framework} page body, call nifra_example (it ships verified ${framework} snippets) rather than guessing the SFC shape.`,
+  }
+}
+
+function resolveInsideCwd(cwd: string, relativeFile: string): string {
+  const root = resolve(cwd)
+  const target = resolve(root, relativeFile)
+  if (target !== root && !target.startsWith(`${root}${sep}`)) {
+    throw new Error(`refusing to write outside project root: ${relativeFile}`)
+  }
+  return target
+}
+
+/** Write a scaffolded route stub when the framework has a verified ready-to-write body. The write is
+ * intentionally conservative: it refuses non-JSX stubs (where we only return contract guidance) and
+ * uses `wx`, so an agent cannot overwrite user work by accident. */
+export async function writeScaffoldRoute(
+  cwd: string,
+  urlPath: string,
+  framework: Framework,
+): Promise<ScaffoldWriteResult> {
+  const result = scaffoldRoute(urlPath, framework)
+  if (result.content === undefined) {
+    return {
+      ...result,
+      written: false,
+      reason: "no verified ready-to-write stub for this framework; use nifra_example for the body",
+    }
+  }
+  const target = resolveInsideCwd(cwd, result.file)
+  await mkdir(dirname(target), { recursive: true })
+  try {
+    await writeFile(target, result.content, { flag: "wx" })
+  } catch (err) {
+    if (err && typeof err === "object" && (err as { code?: string }).code === "EEXIST") {
+      return { ...result, written: false, reason: `file already exists: ${result.file}` }
+    }
+    throw err
+  }
+  return { ...result, written: true }
+}
+
+/** Render the tool result as markdown — the file path, the stub (if any), and the contract note. */
+export function renderScaffold(urlPath: string, framework: Framework): string {
+  let r: ScaffoldResult
+  try {
+    r = scaffoldRoute(urlPath, framework)
+  } catch (err) {
+    return `Cannot scaffold ${JSON.stringify(urlPath)}: ${err instanceof Error ? err.message : String(err)}`
+  }
+  const stub = r.content ? `\n\n\`\`\`${EXT[framework]}\n${r.content}\`\`\`` : ""
+  return `# Scaffold route \`${urlPath}\` (${framework})\n\n**File:** \`${r.file}\`\n\n${r.note}${stub}`
+}

package/src/search-terms.ts

@@ -0,0 +1,89 @@
+/**
+ * Tiny deterministic query expansion for the agent-facing docs/example search tools.
+ *
+ * This is intentionally not "semantic search": the corpora are small, curated, and bundled with the
+ * package. A few framework-specific aliases plus safe prefix matching cover the common human/agent
+ * wording drift ("authentication" vs "auth", "ws" vs "websocket") without adding dependencies,
+ * model calls, or nondeterministic ranking.
+ */
+
+export interface SearchTermGroup {
+  readonly term: string
+  readonly variants: readonly string[]
+}
+
+const ALIASES: Readonly<Record<string, readonly string[]>> = {
+  action: ["actions"],
+  actions: ["action"],
+  api: ["backend", "server"],
+  auth: ["authentication", "login", "session", "sessions"],
+  authentication: ["auth", "login", "session", "sessions"],
+  backend: ["api", "server"],
+  cache: ["caching", "isr"],
+  caching: ["cache", "isr"],
+  client: ["typed"],
+  deploy: ["deployment", "edge", "worker", "workers", "vercel", "deno"],
+  deployment: ["deploy", "edge", "worker", "workers", "vercel", "deno"],
+  loader: ["loaders"],
+  loaders: ["loader"],
+  route: ["routes", "routing"],
+  routes: ["route", "routing"],
+  schema: ["schemas", "validation", "validate"],
+  schemas: ["schema", "validation", "validate"],
+  server: ["api", "backend"],
+  session: ["sessions", "auth", "authentication", "cookie", "cookies"],
+  sessions: ["session", "auth", "authentication", "cookie", "cookies"],
+  sse: ["eventsource", "stream", "streams"],
+  typed: ["client", "type", "types"],
+  upload: ["uploads", "file"],
+  uploads: ["upload", "file"],
+  validate: ["validation", "schema", "schemas"],
+  validation: ["validate", "schema", "schemas"],
+  websocket: ["websockets", "ws"],
+  websockets: ["websocket", "ws"],
+  ws: ["websocket", "websockets"],
+}
+
+export const tokenize = (s: string): string[] =>
+  s
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length > 1)
+
+export function queryTermGroups(query: string): SearchTermGroup[] {
+  return [...new Set(tokenize(query))].map((term) => ({
+    term,
+    variants: [term, ...(ALIASES[term] ?? [])],
+  }))
+}
+
+function tokenMatches(term: string, token: string): boolean {
+  if (term === token) return true
+  // Prefix matching catches plural/stem variants without letting very short terms get noisy.
+  return term.length >= 4 && token.length >= 4 && (term.startsWith(token) || token.startsWith(term))
+}
+
+export function tokenSetHas(tokens: ReadonlySet<string>, group: SearchTermGroup): boolean {
+  for (const variant of group.variants) {
+    for (const token of tokens) {
+      if (tokenMatches(variant, token)) return true
+    }
+  }
+  return false
+}
+
+export function countBodyHits(lowerBody: string, group: SearchTermGroup, maxHits: number): number {
+  let best = 0
+  for (const variant of group.variants) {
+    let from = 0
+    let hits = 0
+    while (hits < maxHits) {
+      const at = lowerBody.indexOf(variant, from)
+      if (at === -1) break
+      hits++
+      from = at + variant.length
+    }
+    if (hits > best) best = hits
+  }
+  return best
+}

package/src/test-tool.ts

@@ -0,0 +1,181 @@
+export interface TestToolArgs {
+  readonly pattern?: unknown
+  readonly timeoutMs?: unknown
+}
+
+export interface TestSummary {
+  readonly passed?: number
+  readonly failed?: number
+  readonly skipped?: number
+  readonly expectations?: number
+  readonly files?: number
+}
+
+export interface TestToolResult {
+  readonly ok: boolean
+  readonly command: readonly string[]
+  readonly durationMs: number
+  readonly exitCode: number | null
+  readonly timedOut: boolean
+  readonly cancelled?: boolean
+  readonly summary: TestSummary
+  readonly stdout: string
+  readonly stderr: string
+  readonly error?: string
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const MAX_TIMEOUT_MS = 300_000
+const MAX_OUTPUT_CHARS = 12_000
+
+function normalizePattern(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "string") throw new Error("pattern must be a string")
+  const pattern = value.trim()
+  if (pattern === "") return undefined
+  if (pattern.length > 500) throw new Error("pattern is too long")
+  if (pattern.includes("\0")) throw new Error("pattern contains a NUL byte")
+  // It is passed as argv, not a shell string, but blocking flags keeps the MCP tool's contract simple:
+  // `pattern` narrows test files; it is not a remote flag injection surface.
+  if (pattern.startsWith("-"))
+    throw new Error("pattern must be a file/path pattern, not a CLI flag")
+  return pattern
+}
+
+function normalizeTimeout(value: unknown): number {
+  if (value === undefined || value === null) return DEFAULT_TIMEOUT_MS
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error("timeoutMs must be a finite number")
+  }
+  return Math.min(Math.max(Math.trunc(value), 1_000), MAX_TIMEOUT_MS)
+}
+
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g")
+
+function clean(text: string): string {
+  const stripped = text.replace(ANSI, "")
+  return stripped.length <= MAX_OUTPUT_CHARS
+    ? stripped
+    : `${stripped.slice(0, 4_000)}\n…(trimmed ${stripped.length - MAX_OUTPUT_CHARS} chars)…\n${stripped.slice(-8_000)}`
+}
+
+function firstNumber(pattern: RegExp, text: string): number | undefined {
+  const match = pattern.exec(text)
+  return match?.[1] === undefined ? undefined : Number(match[1])
+}
+
+function parseSummary(output: string): TestSummary {
+  const passed = firstNumber(/(\d+)\s+pass(?:ed)?\b/i, output)
+  const failed = firstNumber(/(\d+)\s+fail(?:ed)?\b/i, output)
+  const skipped = firstNumber(/(\d+)\s+skip(?:ped)?\b/i, output)
+  const expectations = firstNumber(/(\d+)\s+expect(?:ation)?s?\b/i, output)
+  const files = firstNumber(/(\d+)\s+files?\b/i, output)
+  return {
+    ...(passed !== undefined ? { passed } : {}),
+    ...(failed !== undefined ? { failed } : {}),
+    ...(skipped !== undefined ? { skipped } : {}),
+    ...(expectations !== undefined ? { expectations } : {}),
+    ...(files !== undefined ? { files } : {}),
+  }
+}
+
+/** Run `bun test` in a project with bounded runtime and bounded output. Arguments are argv entries,
+ * never a shell string, so an agent can safely pass a path pattern without command injection risk. */
+export async function collectTestResult(
+  cwd: string,
+  args: TestToolArgs = {},
+  opts: { readonly signal?: AbortSignal } = {},
+): Promise<TestToolResult> {
+  let pattern: string | undefined
+  let timeoutMs: number
+  try {
+    pattern = normalizePattern(args.pattern)
+    timeoutMs = normalizeTimeout(args.timeoutMs)
+  } catch (err) {
+    return {
+      ok: false,
+      command: ["bun", "test"],
+      durationMs: 0,
+      exitCode: null,
+      timedOut: false,
+      summary: {},
+      stdout: "",
+      stderr: "",
+      error: err instanceof Error ? err.message : String(err),
+    }
+  }
+
+  const command = ["bun", "test", ...(pattern === undefined ? [] : [pattern])]
+  const started = Date.now()
+  if (opts.signal?.aborted) {
+    return {
+      ok: false,
+      command,
+      durationMs: 0,
+      exitCode: null,
+      timedOut: false,
+      cancelled: true,
+      summary: {},
+      stdout: "",
+      stderr: "",
+      error:
+        typeof opts.signal.reason === "string" && opts.signal.reason.length > 0
+          ? `cancelled: ${opts.signal.reason}`
+          : "cancelled",
+    }
+  }
+  const proc = Bun.spawn(command, {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  let timedOut = false
+  let cancelled = false
+  const abort = (): void => {
+    cancelled = true
+    proc.kill()
+  }
+  opts.signal?.addEventListener("abort", abort, { once: true })
+  const timer = setTimeout(() => {
+    timedOut = true
+    proc.kill()
+  }, timeoutMs)
+  let stdoutRaw = ""
+  let stderrRaw = ""
+  let exitCode: number | null = null
+  try {
+    const result = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+    stdoutRaw = result[0]
+    stderrRaw = result[1]
+    exitCode = result[2]
+  } finally {
+    clearTimeout(timer)
+    opts.signal?.removeEventListener("abort", abort)
+  }
+  const stdout = clean(stdoutRaw)
+  const stderr = clean(stderrRaw)
+  const combined = `${stdout}\n${stderr}`
+  return {
+    ok: exitCode === 0 && !timedOut && !cancelled,
+    command,
+    durationMs: Date.now() - started,
+    exitCode,
+    timedOut,
+    ...(cancelled ? { cancelled: true } : {}),
+    summary: parseSummary(combined),
+    stdout,
+    stderr,
+    ...(cancelled
+      ? {
+          error:
+            typeof opts.signal?.reason === "string" && opts.signal.reason.length > 0
+              ? `cancelled: ${opts.signal.reason}`
+              : "cancelled",
+        }
+      : {}),
+  }
+}