frontier-os-app-builder 1.0.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,9 +270,9 @@ const MODULE_KEYWORDS = {
                'withdraw', 'off-ramp', 'bank', 'fiat', 'subscription', 'billing', 'price',
                'cost', 'fee', 'tip', 'donate', 'donation'],
     getter: 'sdk.getWallet()',
-    commonMethods: ['getBalance', 'getBalanceFormatted', 'transferFrontierDollar', 'payWithFrontierDollar'],
-    permissions: ['wallet:getBalance', 'wallet:getBalanceFormatted', 'wallet:getAddress',
-                  'wallet:transferFrontierDollar', 'wallet:payWithFrontierDollar']
+    commonMethods: ['getBalance', 'transferFrontierDollar', 'transferOverallFrontierDollar'],
+    permissions: ['wallet:getBalance', 'wallet:getAddress',
+                  'wallet:transferFrontierDollar', 'wallet:transferOverallFrontierDollar']
   },
   User: {
     keywords: ['user', 'profile', 'account', 'member', 'membership', 'auth', 'login',
@@ -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',
@@ -415,8 +417,21 @@ function cmdValidateStructure(cwd, flags) {
   const issues = [];
   const checks = [];
 
-  const requiredFiles = [
-    'src/lib/sdk-context.tsx',
+  // Determine verification tier from manifest sdkPhase
+  const manifest = loadManifest(cwd);
+  const sdkPhase = manifest && manifest.sdkPhase != null ? manifest.sdkPhase : 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 && effectivePhase != null && effectivePhase === sdkPhase;
+  // Backward compat: if no sdkPhase in manifest, run all checks (legacy SDK-first apps)
+  const isLegacy = sdkPhase == null;
+
+  // Tier 1 required files (always checked)
+  const tier1Files = [
+    'src/lib/frontier-services.tsx',
     'src/views/Layout.tsx',
     'src/main.tsx',
     'src/styles/index.css',
@@ -428,42 +443,74 @@ function cmdValidateStructure(cwd, flags) {
     'package.json'
   ];
 
+  // Tier 2 / legacy additional required files
+  const tier2Files = [
+    'src/lib/sdk-context.tsx',
+    'src/lib/sdk-services.tsx'
+  ];
+
+  // Legacy apps use sdk-context.tsx instead of frontier-services.tsx
+  const requiredFiles = isLegacy
+    ? ['src/lib/sdk-context.tsx', 'src/views/Layout.tsx', 'src/main.tsx', 'src/styles/index.css', 'vite.config.ts', 'tsconfig.json', 'postcss.config.js', 'vercel.json', 'index.html', 'package.json']
+    : isTier2
+      ? [...tier1Files, ...tier2Files]
+      : tier1Files;
+
   for (const file of requiredFiles) {
     const exists = fs.existsSync(path.join(cwd, file));
     checks.push({ file, exists });
     if (!exists) issues.push(`Missing required file: ${file}`);
   }
 
-  // Check vercel.json has all 5 CORS origins
-  const vercelPath = path.join(cwd, 'vercel.json');
-  if (fs.existsSync(vercelPath)) {
-    const vercel = readFile(vercelPath);
-    const origins = [
-      'http://localhost:5173',
-      'https://sandbox.os.frontiertower.io',
-      'https://alpha.os.frontiertower.io',
-      'https://beta.os.frontiertower.io',
-      'https://os.frontiertower.io'
-    ];
-    for (const origin of origins) {
-      if (!vercel.includes(origin)) {
-        issues.push(`vercel.json missing CORS origin: ${origin}`);
+  // CORS origin checks — Tier 2 or legacy only
+  if (isLegacy || isTier2) {
+    const vercelPath = path.join(cwd, 'vercel.json');
+    if (fs.existsSync(vercelPath)) {
+      const vercel = readFile(vercelPath);
+      const origins = [
+        'http://localhost:5173',
+        'https://sandbox.os.frontiertower.io',
+        'https://os.frontiertower.io'
+      ];
+      for (const origin of origins) {
+        if (!vercel.includes(origin)) {
+          issues.push(`vercel.json missing CORS origin: ${origin}`);
+        }
       }
     }
   }
 
-  // Check Layout.tsx has iframe detection
-  const layoutPath = path.join(cwd, 'src/views/Layout.tsx');
-  if (fs.existsSync(layoutPath)) {
-    const layout = readFile(layoutPath);
-    if (!layout.includes('isInFrontierApp')) {
-      issues.push('Layout.tsx missing isInFrontierApp() check');
-    }
-    if (!layout.includes('createStandaloneHTML') && !layout.includes('renderStandaloneMessage')) {
-      issues.push('Layout.tsx missing standalone fallback');
+  // Layout SDK checks — Tier 2 or legacy only
+  if (isLegacy || isTier2) {
+    const layoutPath = path.join(cwd, 'src/views/Layout.tsx');
+    if (fs.existsSync(layoutPath)) {
+      const layout = readFile(layoutPath);
+      if (!layout.includes('isInFrontierApp')) {
+        issues.push('Layout.tsx missing isInFrontierApp() check');
+      }
+      if (!layout.includes('createStandaloneHTML') && !layout.includes('renderStandaloneMessage')) {
+        issues.push('Layout.tsx missing standalone fallback');
+      }
+      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)');
+      }
     }
-    if (!layout.includes('SdkProvider')) {
-      issues.push('Layout.tsx missing SdkProvider wrapping');
+  }
+
+  // Mock layer checks — Tier 1 only (non-legacy apps)
+  if (!isLegacy) {
+    const servicesPath = path.join(cwd, 'src/lib/frontier-services.tsx');
+    if (fs.existsSync(servicesPath)) {
+      const services = readFile(servicesPath);
+      if (!services.includes('useServices')) {
+        issues.push('frontier-services.tsx missing useServices export');
+      }
+      if (!services.includes('createMockServices')) {
+        issues.push('frontier-services.tsx missing createMockServices export');
+      }
     }
   }
 
@@ -486,7 +533,8 @@ function cmdValidateStructure(cwd, flags) {
     pass: issues.length === 0,
     checks,
     issues,
-    checkedFiles: requiredFiles.length
+    checkedFiles: requiredFiles.length,
+    tier: isLegacy ? 'legacy' : isTier2 ? 2 : 1
   }, flags);
 }
 
@@ -495,9 +543,19 @@ function cmdValidatePermissions(cwd, flags) {
   if (!manifest) error('.frontier-app/manifest.json not found');
 
   const issues = [];
+  const warnings = [];
   const srcDir = path.join(cwd, 'src');
 
-  // Find all SDK method calls in source
+  // Determine tier
+  const sdkPhase = manifest.sdkPhase != null ? manifest.sdkPhase : 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;
+  const isTier2 = sdkPhase != null && effectivePhase != null && effectivePhase === sdkPhase;
+  const isLegacy = sdkPhase == null;
+
+  // Find all SDK method calls in source (both patterns)
   const usedMethods = new Set();
   function scanDir(dir) {
     if (!fs.existsSync(dir)) return;
@@ -506,9 +564,21 @@ function cmdValidatePermissions(cwd, flags) {
         scanDir(path.join(dir, entry.name));
       } else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
         const content = readFile(path.join(dir, entry.name));
-        // Match sdk.getX().methodName() or getX().methodName() patterns
-        const calls = content.match(/\.(getWallet|getUser|getStorage|getChain|getEvents|getCommunities|getPartnerships|getOffices|getThirdParty)\(\)\.\w+/g);
-        if (calls) calls.forEach(c => usedMethods.add(c.slice(1)));
+        // Match sdk.getX().methodName() or getX().methodName() patterns (legacy/SDK phase)
+        const sdkCalls = content.match(/\.(getWallet|getUser|getStorage|getChain|getEvents|getCommunities|getPartnerships|getOffices|getThirdParty|getNavigation)\(\)\.\w+/g);
+        if (sdkCalls) sdkCalls.forEach(c => usedMethods.add(c.slice(1)));
+        // Match services.module.methodName() patterns (standalone-first)
+        const svcCalls = content.match(/services\.(wallet|user|storage|chain|events|communities|partnerships|offices|thirdParty|navigation)\.\w+/g);
+        if (svcCalls) {
+          svcCalls.forEach(c => {
+            // Convert services.wallet.getBalance to getWallet().getBalance
+            const parts = c.replace('services.', '').split('.');
+            const moduleMap = { wallet: 'getWallet', user: 'getUser', storage: 'getStorage', chain: 'getChain', events: 'getEvents', communities: 'getCommunities', partnerships: 'getPartnerships', offices: 'getOffices', thirdParty: 'getThirdParty', navigation: 'getNavigation' };
+            if (moduleMap[parts[0]] && parts[1]) {
+              usedMethods.add(`${moduleMap[parts[0]]}().${parts[1]}`);
+            }
+          });
+        }
       }
     }
   }
@@ -529,14 +599,20 @@ 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 });
       }
     }
   }
 
   if (missingPerms.length > 0) {
-    issues.push(...missingPerms.map(m => `SDK method ${m.method} used but permission ${m.permission} not in manifest`));
+    if (isLegacy || isTier2) {
+      // Legacy or SDK Integration phase: missing permissions are errors
+      issues.push(...missingPerms.map(m => `SDK method ${m.method} used but permission ${m.permission} not in manifest`));
+    } else {
+      // Feature phases: missing permissions are warnings only
+      warnings.push(...missingPerms.map(m => `Service method ${m.method} used — permission ${m.permission} should be in manifest for SDK Integration`));
+    }
   }
 
   output({
@@ -544,7 +620,9 @@ function cmdValidatePermissions(cwd, flags) {
     declaredPermissions: manifest.permissions,
     usedMethods: Array.from(usedMethods),
     issues,
-    missingPermissions: missingPerms
+    warnings,
+    missingPermissions: missingPerms,
+    tier: isLegacy ? 'legacy' : isTier2 ? 2 : 1
   }, flags);
 }
 
@@ -701,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]); }
   }
 
@@ -786,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

@@ -1,7 +1,7 @@
 ---
 name: fos:new-app
 description: Create a new Frontier OS app from a natural language description
-argument-hint: '"app description" [--auto]'
+argument-hint: '"app description"'
 allowed-tools:
   - Read
   - Write
@@ -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.0.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",