veryfront 0.1.111 → 0.1.113

package/src/cli/shared/json-output.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared JSON output utilities for CLI commands
+ *
+ * Provides consistent structured output for agent consumption.
+ * All commands use the same envelope format.
+ *
+ * @module cli/shared/json-output
+ */
+
+/** Whether the current command should output JSON */
+let _jsonMode = false;
+
+/** Whether the current command should write output to a file */
+let _outputPath: string | null = null;
+
+export function setJsonMode(enabled: boolean): void {
+  _jsonMode = enabled;
+}
+
+export function isJsonMode(): boolean {
+  return _jsonMode;
+}
+
+export function setOutputPath(path: string | null): void {
+  _outputPath = path;
+}
+
+export function getOutputPath(): string | null {
+  return _outputPath;
+}
+
+export interface SuccessEnvelope<T = unknown> {
+  success: true;
+  command: string;
+  data: T;
+  timing?: { duration_ms: number };
+}
+
+export interface ErrorEnvelope {
+  success: false;
+  command: string;
+  error: {
+    code: string;
+    slug: string;
+    message: string;
+    context?: Record<string, unknown>;
+  };
+}
+
+export type JsonEnvelope<T = unknown> = SuccessEnvelope<T> | ErrorEnvelope;
+
+export function createSuccessEnvelope<T>(
+  command: string,
+  data: T,
+  timing?: { duration_ms: number },
+): SuccessEnvelope<T> {
+  const envelope: SuccessEnvelope<T> = { success: true, command, data };
+  if (timing) envelope.timing = timing;
+  return envelope;
+}
+
+export function createErrorEnvelope(
+  command: string,
+  error: { code: string; slug: string; message: string; context?: Record<string, unknown> },
+): ErrorEnvelope {
+  return { success: false, command, error };
+}
+
+export function formatJsonOutput(envelope: JsonEnvelope): string {
+  return JSON.stringify(envelope, null, 2);
+}
+
+/**
+ * Print JSON envelope to stdout.
+ * If --output was specified, also write to file.
+ */
+export async function outputJson(envelope: JsonEnvelope): Promise<void> {
+  const json = formatJsonOutput(envelope);
+  console.log(json);
+
+  if (_outputPath) {
+    const { dirname } = await import("../../src/platform/compat/path/index.js");
+    const { createFileSystem } = await import("../../src/platform/index.js");
+    const fs = createFileSystem();
+    await fs.mkdir(dirname(_outputPath), { recursive: true });
+    await fs.writeTextFile(_outputPath, json);
+  }
+}
+
+/**
+ * Write a single NDJSON line to stdout.
+ * Used for streaming output from long-running commands.
+ */
+export function streamJsonLine(event: Record<string, unknown>): void {
+  console.log(JSON.stringify(event));
+}

package/src/cli/shared/suggest.ts

@@ -0,0 +1,33 @@
+/**
+ * Command suggestion via Levenshtein distance
+ *
+ * @module cli/shared/suggest
+ */
+
+export function levenshtein(a: string, b: string): number {
+  const matrix: number[][] = [];
+  for (let i = 0; i <= a.length; i++) matrix[i] = [i];
+  for (let j = 0; j <= b.length; j++) matrix[0]![j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      matrix[i]![j] = Math.min(
+        matrix[i - 1]![j]! + 1,
+        matrix[i]![j - 1]! + 1,
+        matrix[i - 1]![j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+  }
+  return matrix[a.length]![b.length]!;
+}
+
+export function suggestCommand(
+  input: string,
+  commands: string[],
+  maxDistance = 2,
+): string[] {
+  return commands
+    .map((cmd) => ({ cmd, dist: levenshtein(input, cmd) }))
+    .filter(({ dist }) => dist <= maxDistance)
+    .sort((a, b) => a.dist - b.dist)
+    .map(({ cmd }) => cmd);
+}

package/src/cli/skills/core-skills.ts

@@ -0,0 +1,233 @@
+/**
+ * Core skills embedded as data for compiled binary support.
+ *
+ * When running from source, the loader reads from cli/mcp/skills/.
+ * When compiled, this module provides the same data without filesystem access.
+ */
+
+import type { LoadedSkill } from "./types.js";
+
+export const CORE_SKILLS: LoadedSkill[] = [
+  {
+    manifest: {
+      name: "scaffold-app",
+      version: "1.0.0",
+      description: "Scaffold a new Veryfront app with the right structure, config, and conventions",
+      requires: {
+        cli: ["init", "dev", "doctor"],
+        mcp: ["vf_list_templates", "vf_create_project"],
+      },
+      inputs: {
+        name: { type: "string", description: "Project name" },
+        template: {
+          type: "string",
+          default: "minimal",
+          description: "Template to use",
+        },
+      },
+    },
+    skillMd: `# Scaffold App
+
+Create a new Veryfront application with proper structure and conventions.
+
+## Steps
+
+1. **Discover templates**
+   \`\`\`bash
+   veryfront schema --json | jq '.commands[] | select(.name == "init")'
+   \`\`\`
+
+2. **Create project**
+   \`\`\`bash
+   veryfront init <name> --template <template> --yes --json
+   \`\`\`
+   Expected: \`{ "success": true, "command": "init", "data": { "projectDir": "..." } }\`
+
+3. **Verify project health**
+   \`\`\`bash
+   cd <name>
+   veryfront doctor --json
+   \`\`\`
+
+4. **Start dev server**
+   \`\`\`bash
+   veryfront dev
+   \`\`\`
+
+## Error Recovery
+
+- **init fails**: Check template name, retry with --force
+- **doctor fails**: Fix missing dependencies
+- **dev fails**: Run veryfront clean, then retry`,
+    directory: "core:scaffold-app",
+  },
+  {
+    manifest: {
+      name: "scaffold-ai-app",
+      version: "1.0.0",
+      description: "Scaffold a Veryfront app with AI tools, agent definitions, and knowledge base",
+      requires: {
+        cli: ["init", "dev", "doctor", "workflow"],
+        mcp: ["vf_list_templates", "vf_create_project", "vf_scaffold"],
+      },
+      inputs: {
+        name: { type: "string", description: "Project name" },
+        provider: {
+          type: "string",
+          default: "anthropic",
+          description: "AI provider to configure",
+        },
+      },
+    },
+    skillMd: `# Scaffold AI App
+
+Create a Veryfront app with AI capabilities.
+
+## Steps
+
+1. \`veryfront init <name> --template ai --yes --json\`
+2. \`veryfront install --with ai --yes --json\`
+3. Use vf_scaffold to generate AI components
+4. Configure provider API key in .env
+5. \`veryfront doctor --json\` then \`veryfront dev\`
+
+## Error Recovery
+
+- **Missing API key**: Set provider key in .env
+- **Tool generation fails**: Use vf_get_conventions, scaffold manually`,
+    directory: "core:scaffold-ai-app",
+  },
+  {
+    manifest: {
+      name: "deploy-safely",
+      version: "1.0.0",
+      description: "Build, test, deploy, and verify — with automatic rollback on failure",
+      requires: {
+        cli: ["build", "test", "deploy"],
+        mcp: ["vf_get_errors"],
+      },
+      inputs: {
+        environment: {
+          type: "string",
+          default: "production",
+          description: "Target environment",
+        },
+        branch: {
+          type: "string",
+          default: "main",
+          description: "Branch to deploy",
+        },
+      },
+    },
+    skillMd: `# Deploy Safely
+
+Build, test, deploy, and verify — with rollback on failure.
+
+## Steps
+
+1. \`veryfront build --json\` — abort if success: false
+2. \`veryfront test --json\` — abort if any test fails
+3. \`veryfront deploy --env <environment> --branch <branch> --yes --json\`
+4. Use vf_get_errors to verify no runtime errors after deploy
+5. If errors: redeploy previous version
+
+## Error Recovery
+
+- **Build fails**: Check vf_get_errors, fix and retry
+- **Tests fail**: Read JSON output, fix failing tests
+- **Deploy fails**: Check environment, auth, branch
+- **Post-deploy errors**: Redeploy previous release`,
+    directory: "core:deploy-safely",
+  },
+  {
+    manifest: {
+      name: "debug-build",
+      version: "1.0.0",
+      description: "Diagnose and fix build failures using structured error output",
+      requires: {
+        cli: ["build", "doctor"],
+        mcp: ["vf_get_errors", "vf_get_debug_context"],
+      },
+    },
+    skillMd: `# Debug Build
+
+Diagnose and fix build failures.
+
+## Steps
+
+1. \`veryfront build --json\` — capture error envelope
+2. Use vf_get_errors and vf_get_debug_context for details
+3. Common issues: import resolution, type errors, config errors
+4. Apply fix, rebuild: \`veryfront build --json\`
+5. \`veryfront doctor --json\` to verify health
+
+## Error Recovery
+
+- **Module not found**: Check deno.json imports map
+- **Type errors**: Run deno check for diagnostics
+- **Config invalid**: Compare against fresh veryfront init`,
+    directory: "core:debug-build",
+  },
+  {
+    manifest: {
+      name: "debug-runtime",
+      version: "1.0.0",
+      description: "Diagnose runtime errors by connecting to dev server via MCP",
+      requires: {
+        cli: ["dev"],
+        mcp: ["vf_get_errors", "vf_get_debug_context"],
+      },
+    },
+    skillMd: `# Debug Runtime
+
+Diagnose runtime errors via MCP.
+
+## Steps
+
+1. Ensure \`veryfront dev\` is running (MCP on port 9999)
+2. Use vf_get_errors for current runtime errors
+3. Use vf_get_debug_context for stack traces
+4. Read veryfront://logs resource for server logs
+5. Identify failing route/component, fix source
+6. HMR auto-reloads; use vf_get_errors to confirm fix
+
+## Error Recovery
+
+- **Dev server not running**: Start with veryfront dev
+- **MCP not responding**: Check port 9999, restart
+- **Error persists**: veryfront clean, restart dev`,
+    directory: "core:debug-runtime",
+  },
+  {
+    manifest: {
+      name: "contribute",
+      version: "1.0.0",
+      description: "Onboard to veryfront-code — architecture, testing, conventions, PR process",
+      requires: {
+        cli: ["test", "lint", "schema"],
+        mcp: ["vf_get_conventions"],
+      },
+    },
+    skillMd: `# Contribute
+
+Onboard to the veryfront-code repository.
+
+## Steps
+
+1. Read AGENTS.md and cli/AGENTS.md for conventions
+2. Use vf_get_conventions for coding patterns
+3. \`veryfront schema --json\` to understand available commands
+4. Follow patterns: hash imports, defineError(), createArgParser()
+5. \`veryfront test --json\` to run tests
+6. \`veryfront lint --json\` to lint
+7. \`deno fmt\` to format
+
+## PR Checklist
+
+- Tests pass (veryfront test)
+- Lint clean (veryfront lint)
+- Formatted (deno fmt --check)
+- Commands registered in router.ts AND command-definitions.ts`,
+    directory: "core:contribute",
+  },
+];

package/src/cli/skills/loader.ts

@@ -0,0 +1,98 @@
+import { createFileSystem } from "../../src/platform/index.js";
+import { cwd } from "../../src/platform/index.js";
+import { type LoadedSkill, parseSkillJson } from "./types.js";
+import { CORE_SKILLS } from "./core-skills.js";
+
+function getCoreSkillsDir(): string {
+  return new URL("../mcp/skills", import.meta.url).pathname;
+}
+
+export async function loadSkill(
+  directory: string,
+): Promise<LoadedSkill | null> {
+  const fs = createFileSystem();
+
+  try {
+    const manifestRaw = await fs.readTextFile(`${directory}/skill.json`);
+    const manifest = parseSkillJson(JSON.parse(manifestRaw));
+    if (!manifest.success) return null;
+
+    const skillMd = await fs.readTextFile(`${directory}/SKILL.md`).catch(
+      () => "",
+    );
+    return { manifest: manifest.data, skillMd, directory };
+  } catch {
+    return null;
+  }
+}
+
+export async function listCoreSkills(): Promise<LoadedSkill[]> {
+  const fs = createFileSystem();
+  const skills: LoadedSkill[] = [];
+  const skillsDir = getCoreSkillsDir();
+
+  try {
+    for await (const entry of fs.readDir(skillsDir)) {
+      if (!entry.isDirectory) continue;
+      const skill = await loadSkill(`${skillsDir}/${entry.name}`);
+      if (skill) skills.push(skill);
+    }
+  } catch {
+    // Filesystem skills not available (compiled binary) — use embedded
+  }
+
+  // Fall back to embedded core skills if none loaded from filesystem
+  if (skills.length === 0) {
+    return CORE_SKILLS;
+  }
+
+  return skills;
+}
+
+/**
+ * Scan the current working directory for local skill directories.
+ * A local skill is any subdirectory containing a skill.json file.
+ */
+export async function listLocalSkills(): Promise<LoadedSkill[]> {
+  const fs = createFileSystem();
+  const skills: LoadedSkill[] = [];
+  const dir = cwd();
+
+  try {
+    for await (const entry of fs.readDir(dir)) {
+      if (!entry.isDirectory) continue;
+      const skill = await loadSkill(`${dir}/${entry.name}`);
+      if (skill) skills.push(skill);
+    }
+  } catch {
+    // cwd not readable
+  }
+
+  return skills;
+}
+
+/**
+ * List all skills: core (built-in) + local (in cwd).
+ */
+export async function listAllSkills(): Promise<LoadedSkill[]> {
+  const [core, local] = await Promise.all([
+    listCoreSkills(),
+    listLocalSkills(),
+  ]);
+
+  // Deduplicate by name, local skills override core
+  const seen = new Set<string>();
+  const result: LoadedSkill[] = [];
+
+  for (const skill of local) {
+    seen.add(skill.manifest.name);
+    result.push(skill);
+  }
+  for (const skill of core) {
+    if (!seen.has(skill.manifest.name)) {
+      result.push(skill);
+    }
+  }
+
+  return result;
+}

package/src/cli/skills/types.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export const SkillManifestSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  description: z.string(),
+  requires: z
+    .object({
+      cli: z.array(z.string()).optional(),
+      mcp: z.array(z.string()).optional(),
+    })
+    .optional(),
+  inputs: z
+    .record(
+      z.string(),
+      z.object({
+        type: z.string(),
+        default: z.unknown().optional(),
+        description: z.string().optional(),
+      }),
+    )
+    .optional(),
+});
+
+export type SkillManifest = z.infer<typeof SkillManifestSchema>;
+
+export function parseSkillJson(
+  raw: unknown,
+): { success: true; data: SkillManifest } | { success: false; error: string } {
+  const result = SkillManifestSchema.safeParse(raw);
+  if (result.success) return { success: true, data: result.data };
+  return { success: false, error: result.error.message };
+}
+
+export interface LoadedSkill {
+  manifest: SkillManifest;
+  skillMd: string;
+  directory: string;
+}

package/src/cli/utils/index.ts

@@ -211,6 +211,8 @@ export async function confirmPrompt(
   message: string,
   defaultValue = false,
 ): Promise<boolean> {
+  const { isInteractive } = await import("../shared/interactive.js");
+  if (!isInteractive()) return true;
   if (!isTTY()) return defaultValue;
 
   const hint = defaultValue ? "[Y/n]" : "[y/N]";

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.111",
+  "version": "0.1.113",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "exclude": [
@@ -112,6 +112,8 @@ export default {
     "#veryfront/build": "./src/build/index.ts",
     "#veryfront/cache": "./src/cache/index.ts",
     "#cli/shared/args": "./cli/shared/args.ts",
+    "#cli/shared/json-output": "./cli/shared/json-output.ts",
+    "#cli/shared/interactive": "./cli/shared/interactive.ts",
     "#cli/shared/types": "./cli/shared/types.ts",
     "#cli/shared/constants": "./cli/shared/constants.ts",
     "#cli/shared/config": "./cli/shared/config.ts",

package/src/src/html/dev-scripts.ts

@@ -1,5 +1,7 @@
+import { escapeHtml } from "./html-escape.js";
+
 export function getDevStyles(nonce?: string): string {
-  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
 
   return `
   <style${nonceAttr}>
@@ -32,7 +34,7 @@ export function getDevStyles(nonce?: string): string {
 }
 
 function getNonceAttr(nonce?: string): string {
-  return nonce ? ` nonce="${nonce}"` : "";
+  return nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
 }
 
 export function getDevScripts(_hmrPort?: number, nonce?: string): string {

package/src/src/html/html-injection.ts

@@ -5,6 +5,7 @@ import {
   generateScriptTags,
   generateStyleTags,
 } from "./tag-generators.js";
+import { escapeHtml } from "./html-escape.js";
 import { getDevScripts, getDevStyles, getProdScripts, getStudioScripts } from "./dev-scripts.js";
 
 export interface InjectHTMLContentOptions {
@@ -61,7 +62,7 @@ export function injectHTMLContent(
 
   // Inject import map into <head> for ESM module resolution (must be before any module scripts)
   if (options.importMapJson && /<\/head>/i.test(html)) {
-    const nonceAttr = options.nonce ? ` nonce="${options.nonce}"` : "";
+    const nonceAttr = options.nonce ? ` nonce="${escapeHtml(options.nonce)}"` : "";
     const importMapTag =
       `<script type="importmap"${nonceAttr}>\n${options.importMapJson}\n</script>`;
     html = html.replace(/<\/head>/i, `${importMapTag}\n</head>`);

package/src/src/html/html-shell-generator.ts

@@ -206,7 +206,7 @@ async function generateHTMLShellPartsImpl(
     ? `<link rel="modulepreload" href="${jsxRuntimeUrl}">`
     : "";
 
-  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  const nonceAttr = nonce ? ` nonce="${escapeHTML(nonce)}"` : "";
 
   // Expose project slug for runtime error overlay "Fix in Veryfront" button
   const overlaySlug = options.projectId || meta.slug;

package/src/src/html/hydration-script-builder/dev-client-renderer.ts

@@ -1,7 +1,8 @@
 import { getLoaderScript, getRendererScript, getRouterScript } from "./templates/index.js";
+import { escapeHtml } from "../html-escape.js";
 
 export function generateDevClientRendererScript(nonce?: string): string {
-  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
 
   return `
   <script type="module"${nonceAttr}>

package/src/src/html/hydration-script-builder/dev-component-manifest.ts

@@ -1,10 +1,11 @@
 import type { VeryfrontConfig } from "../../config/index.js";
+import { escapeHtml } from "../html-escape.js";
 
 export function generateDevComponentManifestScript(
   config: VeryfrontConfig,
   nonce?: string,
 ): string {
-  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
   const components = config.dev?.components ?? [];
 
   return `

package/src/src/html/hydration-script-builder/dev-error-logger.ts

@@ -1,5 +1,7 @@
+import { escapeHtml } from "../html-escape.js";
+
 function getOpenScriptTag(nonce?: string): string {
-  return nonce ? `<script nonce="${nonce}">` : "<script>";
+  return nonce ? `<script nonce="${escapeHtml(nonce)}">` : "<script>";
 }
 
 export function generateDevErrorLoggerScript(nonce?: string): string {

package/src/src/html/hydration-script-builder/dev-scripts.ts

@@ -1,5 +1,6 @@
 import type { ComponentProps } from "../../types/index.js";
 import type { VeryfrontConfig } from "../../config/index.js";
+import { escapeHtml } from "../html-escape.js";
 import { generateDevErrorLoggerScript } from "./dev-error-logger.js";
 import { generateDevComponentManifestScript } from "./dev-component-manifest.js";
 import { generateDevClientRendererScript } from "./dev-client-renderer.js";
@@ -12,7 +13,7 @@ function generateHMRScript(
   // Skip dev HMR script when preview-hmr.js will be used instead
   if (skipDevHMR || !config.dev?.hmr) return "";
 
-  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
   return `<script type="module" src="/_veryfront/hmr.js"${nonceAttr}></script>`;
 }
 

package/src/src/html/hydration-script-builder/prod-hydration.ts

@@ -1,4 +1,5 @@
 import type { ComponentProps } from "../../types/index.js";
+import { escapeHtml } from "../html-escape.js";
 
 export function generateProdHydrationScript(
   slug: string,
@@ -6,7 +7,7 @@ export function generateProdHydrationScript(
   props?: ComponentProps,
   nonce?: string,
 ): string {
-  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
   const pageProps = JSON.stringify(props ?? {});
 
   return `

package/src/src/html/hydration-script-builder/prod-scripts.ts

@@ -1,4 +1,5 @@
 import { getLoaderScript, getRendererScript, getRouterScript } from "./templates/index.js";
+import { escapeHtml } from "../html-escape.js";
 
 export function getProdScripts(
   _slug: string,
@@ -6,7 +7,7 @@ export function getProdScripts(
   _props?: Record<string, unknown>,
   nonce?: string,
 ): string {
-  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
 
   return `
   <script type="module"${nonceAttr}>

package/src/src/html/styles-builder/dev-styles.ts

@@ -1,7 +1,8 @@
 import { Z_INDEX_ERROR_OVERLAY } from "../../utils/index.js";
+import { escapeHtml } from "../html-escape.js";
 
 export function getDevStyles(nonce?: string): string {
-  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
 
   return `
   <style${nonceAttr}>