frontier-os-app-builder 1.1.0 → 1.2.0

package/bin/fos-tools.cjs

@@ -10,7 +10,7 @@ const { execSync } = require('child_process');
 // Usage: node fos-tools.cjs <command> [args] [--raw] [--pick <field>]
 // ─────────────────────────────────────────────
 
-const VERSION = '1.0.0';
+const VERSION = '1.2.0';
 
 // ── Helpers ──────────────────────────────────
 
@@ -270,8 +270,8 @@ const MODULE_KEYWORDS = {
                'withdraw', 'off-ramp', 'bank', 'fiat', 'subscription', 'billing', 'price',
                'cost', 'fee', 'tip', 'donate', 'donation'],
     getter: 'sdk.getWallet()',
-    commonMethods: ['getBalance', 'getBalanceFormatted', 'transferFrontierDollar', 'transferOverallFrontierDollar'],
-    permissions: ['wallet:getBalance', 'wallet:getBalanceFormatted', 'wallet:getAddress',
+    commonMethods: ['getBalance', 'transferFrontierDollar', 'transferOverallFrontierDollar'],
+    permissions: ['wallet:getBalance', 'wallet:getAddress',
                   'wallet:transferFrontierDollar', 'wallet:transferOverallFrontierDollar']
   },
   User: {
@@ -287,9 +287,11 @@ const MODULE_KEYWORDS = {
                'reserve', 'reservation', 'space', 'venue', 'location', 'conference',
                'meeting', 'coworking'],
     getter: 'sdk.getEvents()',
-    commonMethods: ['listEvents', 'createEvent', 'listLocations', 'createRoomBooking'],
+    commonMethods: ['listEvents', 'createEvent', 'listLocations', 'createRoomBooking',
+                    'getCryptoDepositPreflight', 'placeCryptoDeposit'],
     permissions: ['events:listEvents', 'events:createEvent', 'events:listLocations',
-                  'events:listRoomBookings', 'events:createRoomBooking']
+                  'events:listRoomBookings', 'events:createRoomBooking',
+                  'events:getCryptoDepositPreflight', 'events:placeCryptoDeposit']
   },
   Communities: {
     keywords: ['community', 'group', 'team', 'club', 'internship', 'intern', 'cohort',
@@ -418,9 +420,12 @@ function cmdValidateStructure(cwd, flags) {
   // Determine verification tier from manifest sdkPhase
   const manifest = loadManifest(cwd);
   const sdkPhase = manifest && manifest.sdkPhase != null ? manifest.sdkPhase : null;
-  const currentPhase = flags.phase ? parseInt(flags.phase, 10) : null;
+  const currentPhase = flags.phase != null && Number.isInteger(+flags.phase) ? +flags.phase : null;
+  // Fallback to STATE.md phase when --phase not passed, so the Tier-2 gate works even if a caller forgets the flag
+  const fallbackPhase = flags.phase == null ? (loadState(cwd)?.frontmatter?.phase ?? null) : null;
+  const effectivePhase = currentPhase ?? fallbackPhase;
   // Tier 2 only when sdkPhase is set AND current phase matches sdkPhase
-  const isTier2 = sdkPhase != null && currentPhase != null && currentPhase === sdkPhase;
+  const isTier2 = sdkPhase != null && effectivePhase != null && effectivePhase === sdkPhase;
   // Backward compat: if no sdkPhase in manifest, run all checks (legacy SDK-first apps)
   const isLegacy = sdkPhase == null;
 
@@ -489,6 +494,9 @@ function cmdValidateStructure(cwd, flags) {
       if (!layout.includes('SdkProvider')) {
         issues.push('Layout.tsx missing SdkProvider wrapping');
       }
+      if (!layout.includes('FrontierServicesProvider')) {
+        issues.push('Layout.tsx missing FrontierServicesProvider bridge (useServices() will crash at runtime)');
+      }
     }
   }
 
@@ -540,8 +548,11 @@ function cmdValidatePermissions(cwd, flags) {
 
   // Determine tier
   const sdkPhase = manifest.sdkPhase != null ? manifest.sdkPhase : null;
-  const currentPhase = flags.phase ? parseInt(flags.phase, 10) : null;
-  const isTier2 = sdkPhase != null && currentPhase != null && currentPhase === sdkPhase;
+  const currentPhase = flags.phase != null && Number.isInteger(+flags.phase) ? +flags.phase : null;
+  // Fallback to STATE.md phase when --phase not passed, so the Tier-2 gate works even if a caller forgets the flag
+  const fallbackPhase = flags.phase == null ? (loadState(cwd)?.frontmatter?.phase ?? null) : null;
+  const effectivePhase = currentPhase ?? fallbackPhase;
+  const isTier2 = sdkPhase != null && effectivePhase != null && effectivePhase === sdkPhase;
   const isLegacy = sdkPhase == null;
 
   // Find all SDK method calls in source (both patterns)
@@ -588,7 +599,7 @@ function cmdValidatePermissions(cwd, flags) {
   for (const method of usedMethods) {
     // Try to find matching permission
     for (const [pattern, perm] of Object.entries(methodToPermission)) {
-      if (method.includes(pattern.split('.')[0]) && !declaredPerms.has(perm)) {
+      if (method === pattern && !declaredPerms.has(perm)) {
         missingPerms.push({ method, permission: perm });
       }
     }
@@ -768,13 +779,14 @@ function cmdCommit(message, files, flags) {
 
 function main() {
   const args = process.argv.slice(2);
-  const flags = { raw: false, pick: null };
+  const flags = { raw: false, pick: null, phase: null };
 
   // Extract flags
   const cleanArgs = [];
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--raw') { flags.raw = true; }
     else if (args[i] === '--pick' && args[i + 1]) { flags.pick = args[++i]; }
+    else if (args[i] === '--phase' && args[i + 1]) { flags.phase = args[++i]; }
     else { cleanArgs.push(args[i]); }
   }
 
@@ -853,6 +865,31 @@ Commands:
       break;
     }
 
+    case 'sdk-ref': {
+      const modulesIdx = rest.indexOf('--modules');
+      if (modulesIdx < 0 || !rest[modulesIdx + 1]) {
+        error('sdk-ref requires --modules <Module1,Module2,...>');
+      }
+      const modules = rest[modulesIdx + 1].split(',').map(m => m.trim().toLowerCase());
+      const fosHome = process.env.FOS_HOME || path.join(require('os').homedir(), '.claude', 'frontier-os-app-builder');
+      const sdkDir = path.join(fosHome, 'references', 'sdk');
+      const always = ['init', 'types'];
+      const allFiles = [...always, ...modules];
+      const parts = [];
+      for (const f of allFiles) {
+        const fp = path.join(sdkDir, `${f}.md`);
+        if (!fs.existsSync(fp)) {
+          error(`SDK reference file not found: ${fp}`);
+        }
+        parts.push(fs.readFileSync(fp, 'utf-8'));
+      }
+      const content = parts.join('\n\n---\n\n');
+      const tmpPath = path.join(require('os').tmpdir(), `fos-sdk-ref-${Date.now()}.md`);
+      fs.writeFileSync(tmpPath, content);
+      console.log(`@file:${tmpPath}`);
+      break;
+    }
+
     default:
       error(`Unknown command: ${command}. Run 'node fos-tools.cjs help' for usage.`);
   }

package/bin/install.js

@@ -10,7 +10,7 @@ const path = require('path');
 // and templates into ~/.claude/
 // ─────────────────────────────────────────────
 
-const VERSION = '1.0.0';
+const VERSION = '1.2.0';
 const PRODUCT = 'frontier-os-app-builder';
 
 // Source: this repo
@@ -104,15 +104,16 @@ function install() {
   log('Installing agents...');
   const agentSrc = path.join(SRC_ROOT, 'agents');
   const agentDest = path.join(CLAUDE_HOME, 'agents');
+  let agentCount = 0;
   if (fs.existsSync(agentSrc)) {
     for (const file of fs.readdirSync(agentSrc)) {
       if (file.startsWith('fos-') && file.endsWith('.md')) {
         const dest = copyFile(path.join(agentSrc, file), path.join(agentDest, file));
         installedFiles.push(dest);
+        agentCount++;
       }
     }
   }
-  const agentCount = installedFiles.filter(f => f.includes('/agents/fos-')).length;
   success(`${agentCount} agents → ~/.claude/agents/`);
 
   // 3. Workflows → ~/.claude/frontier-os-app-builder/workflows/
@@ -149,7 +150,8 @@ function install() {
     success(`CLI tool → ~/.claude/${PRODUCT}/bin/fos-tools.cjs`);
   }
 
-  // 7. Write manifest
+  // 7. Write manifest (record its own path first so uninstall removes it)
+  installedFiles.push(MANIFEST_PATH);
   const manifest = {
     version: VERSION,
     installed_at: new Date().toISOString(),
@@ -157,7 +159,6 @@ function install() {
   };
   ensureDir(path.dirname(MANIFEST_PATH));
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2));
-  installedFiles.push(MANIFEST_PATH);
 
   // Summary
   console.log(`\n\x1b[32m  ✓ Installed ${installedFiles.length} files\x1b[0m\n`);
@@ -185,11 +186,13 @@ function uninstall() {
     }
   }
 
-  // Clean up directories
+  // Clean up directories (deepest-first: prune child dirs before their parents)
   const dirsToClean = [
     path.join(CLAUDE_HOME, 'commands', 'fos'),
     path.join(FOS_HOME, 'workflows'),
+    path.join(FOS_HOME, 'references', 'sdk'),
     path.join(FOS_HOME, 'references'),
+    path.join(FOS_HOME, 'templates', 'app', 'public'),
     path.join(FOS_HOME, 'templates', 'app'),
     path.join(FOS_HOME, 'templates', 'state'),
     path.join(FOS_HOME, 'templates'),

package/commands/fos/add-feature.md

@@ -16,8 +16,7 @@ Add a new feature to the current milestone. Infers required SDK modules, creates
 
 <execution_context>
 @$HOME/.claude/frontier-os-app-builder/workflows/add-feature.md
-@$HOME/.claude/frontier-os-app-builder/references/module-inference.md
-@$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
+@$HOME/.claude/frontier-os-app-builder/references/module-index.md
 </execution_context>
 
 <context>

package/commands/fos/discuss.md

@@ -19,7 +19,6 @@ Gather implementation decisions for a phase by identifying gray areas and discus
 
 <execution_context>
 @$HOME/.claude/frontier-os-app-builder/workflows/discuss.md
-@$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
 </execution_context>
 
 <context>

package/commands/fos/new-app.md

@@ -24,9 +24,7 @@ Initialize a new Frontier OS app through guided flow: gather requirements, infer
 
 <execution_context>
 @$HOME/.claude/frontier-os-app-builder/workflows/new-app.md
-@$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
-@$HOME/.claude/frontier-os-app-builder/references/module-inference.md
-@$HOME/.claude/frontier-os-app-builder/references/app-patterns.md
+@$HOME/.claude/frontier-os-app-builder/references/module-index.md
 </execution_context>
 
 <context>

package/commands/fos/new-milestone.md

@@ -16,7 +16,7 @@ Archive the current milestone and start a new one. Gathers new feature descripti
 
 <execution_context>
 @$HOME/.claude/frontier-os-app-builder/workflows/new-milestone.md
-@$HOME/.claude/frontier-os-app-builder/references/module-inference.md
+@$HOME/.claude/frontier-os-app-builder/references/module-index.md
 </execution_context>
 
 <context>

package/commands/fos/plan.md

@@ -23,8 +23,6 @@ Create execution plans for a phase by researching existing Frontier OS apps, the
 
 <execution_context>
 @$HOME/.claude/frontier-os-app-builder/workflows/plan.md
-@$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
-@$HOME/.claude/frontier-os-app-builder/references/app-patterns.md
 </execution_context>
 
 <context>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontier-os-app-builder",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Meta-prompting framework for building Frontier OS apps with Claude Code",
   "author": "BerlinhouseLabs",
   "license": "MIT",
@@ -16,6 +16,12 @@
     "templates/",
     "README.md"
   ],
+  "scripts": {
+    "prepublishOnly": "node --check bin/install.js && node bin/fos-tools.cjs version"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "keywords": [
     "frontier-os",
     "claude-code",

package/references/app-patterns.md

@@ -13,7 +13,7 @@ Reference for the standard structure, conventions, and tech stack used by all Fr
 | Language     | TypeScript                      | 5.9       |
 | CSS          | Tailwind CSS (via PostCSS)      | 4         |
 | Testing      | Vitest + jsdom + Testing Library| 4 / 27    |
-| SDK          | @frontiertower/frontier-sdk     | 0.21.0    |
+| SDK          | @frontiertower/frontier-sdk     | 0.24.0    |
 | Routing      | react-router-dom                | 7         |
 
 ---
@@ -69,12 +69,12 @@ These files are copied verbatim. They must not be modified per app.
 
 ### `src/lib/frontier-services.tsx`
 
-This file provides the `useServices()` hook and `FrontierServicesProvider`. It is identical across all apps. During standalone development it returns mock services; after SDK Integration it detects the environment and returns either mocks or real SDK-backed services.
+This file provides the `useServices()` hook and `FrontierServicesProvider`. It is identical across all apps and stays **SDK-free** (imports only React) — it is the mock seam. During standalone development `FrontierServicesProvider` returns mock services; after SDK Integration the **Layout** passes it real SDK-backed services in-frame (mocks standalone), so feature code never changes.
 
 ### `src/lib/sdk-context.tsx` — identical across all apps, created during SDK Integration phase (not at scaffold time)
 
 ```tsx
-import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from 'react';
+import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
 import { FrontierSDK } from '@frontiertower/frontier-sdk';
 
 const SdkContext = createContext<FrontierSDK | null>(null);
@@ -86,29 +86,29 @@ export const useSdk = (): FrontierSDK => {
 };
 
 export const SdkProvider = ({ children }: { children: ReactNode }) => {
-  const sdkRef = useRef<FrontierSDK | null>(null);
-  const [ready, setReady] = useState(false);
+  const [sdk, setSdk] = useState<FrontierSDK | null>(null);
 
   useEffect(() => {
-    const sdk = new FrontierSDK();
-    sdkRef.current = sdk;
-    setReady(true);
+    const instance = new FrontierSDK();
+    setSdk(instance);
 
     return () => {
-      sdk.destroy();
+      instance.destroy();
     };
   }, []);
 
-  if (!ready) return null;
+  if (!sdk) return null;
 
   return (
-    <SdkContext.Provider value={sdkRef.current}>
+    <SdkContext.Provider value={sdk}>
       {children}
     </SdkContext.Provider>
   );
 };
 ```
 
+> The SDK is held in `useState` (not a `useRef`): under React StrictMode the effect runs mount → cleanup → mount, so the first instance is created then destroyed. Storing it in state makes the second `setSdk(...)` re-render the Provider with the live instance, instead of leaving consumers pinned to the destroyed one. Do not "simplify" this back to a ref.
+
 ### `src/lib/sdk-services.tsx` — identical across all apps, created during SDK Integration phase (not at scaffold time)
 
 This file provides the adapter that maps the `FrontierServices` interface to real SDK calls. It is created during the SDK Integration phase.
@@ -152,7 +152,7 @@ export default {
 
 ### `vercel.json`
 
-See [deployment.md](deployment.md) for the full file. All apps share the same CORS configuration with 3 origin blocks.
+See [deployment.md](deployment.md) for the full file. All apps share the same `vercel.json`: CORS for the production origin plus a `Content-Security-Policy: frame-ancestors` listing the 3 live Frontier OS origins (production `os.frontiertower.io`, sandbox `sandbox.os.frontiertower.io`, and `localhost:5173`) and the standard security headers.
 
 ---
 
@@ -175,7 +175,7 @@ Fixed fields (do not change):
 - `"private": true`
 - `"type": "module"`
 - `scripts` block (see Package Scripts below)
-- Core dependencies: `@frontiertower/frontier-sdk`, `react`, `react-dom`, `react-router-dom`
+- Core dependencies: `@frontiertower/frontier-sdk`, `react`, `react-dom`, `react-router-dom`, `viem` (`^2.44.0` — for on-chain apps that build calldata for `executeCall`/`executeBatchCall`; safe to drop for pure-UI apps)
 - Core devDependencies: `@tailwindcss/postcss`, `@types/react`, `@types/react-dom`, `@vitejs/plugin-react`, `postcss`, `tailwindcss`, `typescript`, `vite`
 - Test devDependencies (when tests exist): `@testing-library/jest-dom`, `@testing-library/react`, `@testing-library/user-event`, `@vitest/coverage-v8`, `jsdom`, `vitest`
 
@@ -318,9 +318,14 @@ export const Layout = () => {
     );
   }
 
+  // In-frame: SdkProvider provides the SDK; SdkServicesBridge wires it into
+  // FrontierServicesProvider so feature code's useServices() works unchanged.
+  // (SdkServicesBridge helper — see templates/app/layout.tsx.)
   return (
     <SdkProvider>
-      <Outlet />
+      <SdkServicesBridge>
+        <Outlet />
+      </SdkServicesBridge>
     </SdkProvider>
   );
 };
@@ -347,7 +352,7 @@ No iframe detection, no loading state, no standalone fallback. The app just rend
 
 #### SDK-Aware Layout (after SDK Integration phase)
 
-The existing Layout pattern with `isInFrontierApp()`, `createStandaloneHTML()`, and `SdkProvider` wrapping is applied during the SDK Integration phase. See the current Layout Pattern above.
+The Layout pattern with `isInFrontierApp()`, `createStandaloneHTML()`, `SdkProvider`, AND the `FrontierServicesProvider` bridge (so `useServices()` works against the real SDK) is applied during the SDK Integration phase. See the SDK-Aware Layout Pattern above and `templates/app/layout.tsx`.
 
 ---
 
@@ -359,20 +364,21 @@ New apps use the `useServices()` abstraction instead of `useSdk()` directly. Thi
 
 ```typescript
 import { useState, useEffect } from 'react';
+import { formatAmount } from '@frontiertower/frontier-sdk';
 import { useServices } from '../lib/frontier-services';
-import type { WalletBalanceFormatted } from '../lib/frontier-services';
 
 export function useBalance() {
   const services = useServices();
-  const [balance, setBalance] = useState<WalletBalanceFormatted | null>(null);
+  // Balance fields are bigint base units; format them for display with formatAmount().
+  const [balance, setBalance] = useState<string | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
     const fetch = async () => {
       try {
-        const result = await services.wallet.getBalanceFormatted();
-        setBalance(result);
+        const result = await services.wallet.getBalance();
+        setBalance(formatAmount(result.total));
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to load balance');
       } finally {
@@ -417,13 +423,25 @@ export const router = createBrowserRouter([
 ]);
 ```
 
-### Single-Component Variant
+### Simple Apps (Single View)
+
+Even an app with only one view uses the router — there is no "render the Layout directly from `main.tsx`" path. Define a single index route so `Layout` stays in the render tree:
+
+```tsx
+import { createBrowserRouter } from 'react-router-dom';
+import { Layout } from './views/Layout';
+import { Home } from './views/Home';
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <Layout />,
+    children: [{ index: true, element: <Home /> }],
+  },
+]);
+```
 
-For very simple apps that need only one view, the router can be omitted. In this case:
-- `main.tsx` renders the Layout directly instead of `<RouterProvider>`
-- `Layout.tsx` renders the single view component instead of `<Outlet />`
-- No `router.tsx` file needed
-- `react-router-dom` can be removed from dependencies
+Keeping `Layout` mounted preserves the services seam: standalone it provides `FrontierServicesProvider`, and after SDK Integration it wraps the app in `SdkProvider` + `SdkServicesBridge` so `useServices()` resolves against the real SDK. `react-router-dom` stays a dependency. Do not bypass the router by rendering a view straight from `main.tsx` — that skips the Layout bridge and ships mock services in-frame.
 
 ### `main.tsx` (Identical Pattern)
 
@@ -581,9 +599,9 @@ The final phase of every app wires the real Frontier SDK in. This is a mechanica
 1. **Add SDK dependency**: `npm install @frontiertower/frontier-sdk`
 2. **Create `src/lib/sdk-context.tsx`**: Standard SdkProvider + useSdk hook (from template)
 3. **Create `src/lib/sdk-services.tsx`**: Adapter mapping FrontierServices interface to real SDK calls
-4. **Upgrade `src/lib/frontier-services.tsx`**: Add environment detection — iframe uses SDK adapter, standalone uses mocks
-5. **Upgrade `src/views/Layout.tsx`**: Add `isInFrontierApp()` detection, standalone fallback, `SdkProvider` wrapping
-6. **Add CORS origins to `vercel.json`**: All 3 Frontier OS origins
+4. **Leave `src/lib/frontier-services.tsx` unchanged**: it stays the SDK-free mock seam. The iframe/standalone switch happens in Layout (step 5) — do NOT add SDK imports or detection here.
+5. **Swap in `src/views/Layout.tsx`** (from `templates/app/layout.tsx`): `isInFrontierApp()` detection + standalone fallback; in-frame it wraps the app in `SdkProvider` AND bridges the SDK into `FrontierServicesProvider` (via `createSdkServices(sdk)`) so `useServices()` resolves against the real SDK
+6. **Swap in the full `vercel.json`**: CORS for the production origin + `Content-Security-Policy: frame-ancestors` listing the 3 live origins (`os.frontiertower.io`, `sandbox.os.frontiertower.io`, `localhost:5173`) + security headers
 
 After SDK Integration, the app works in both modes:
 - **Standalone** (browser): Uses mock services, shows development data