@fias/create-fias-plugin 1.0.4 → 1.1.0

package/index.js

@@ -7,7 +7,7 @@ var path = require('path');
 
 var TEMPLATE_DIR = path.resolve(__dirname, 'templates/default');
 
-function copyDir(src, dest, replacements) {
+function copyDir(src, dest, replacements, opts) {
   fs.mkdirSync(dest, { recursive: true });
 
   var entries = fs.readdirSync(src, { withFileTypes: true });
@@ -17,8 +17,17 @@ function copyDir(src, dest, replacements) {
     var destPath = path.join(dest, entry.name);
 
     if (entry.isDirectory()) {
-      copyDir(srcPath, destPath, replacements);
+      copyDir(srcPath, destPath, replacements, opts);
     } else {
+      if (opts.inPlace && fs.existsSync(destPath)) {
+        console.error(
+          'Error: refusing to overwrite existing file: ' + path.relative(opts.rootDest, destPath),
+        );
+        console.error(
+          'In --in-place mode, the target directory must not already contain plugin files.',
+        );
+        process.exit(1);
+      }
       var content = fs.readFileSync(srcPath, 'utf-8');
       var keys = Object.keys(replacements);
       for (var k = 0; k < keys.length; k++) {
@@ -29,27 +38,59 @@ function copyDir(src, dest, replacements) {
   }
 }
 
-var projectName = process.argv[2];
-
-if (!projectName) {
+function printUsage() {
   console.error('Usage: npm create @fias/fias-plugin <project-name>');
-  process.exit(1);
+  console.error('   or: npm create @fias/fias-plugin -- --in-place   (scaffold into current directory)');
+  console.error('   or: npm create @fias/fias-plugin .                (alias for --in-place)');
+}
+
+var args = process.argv.slice(2);
+var inPlace = false;
+var positional = [];
+for (var a = 0; a < args.length; a++) {
+  if (args[a] === '--in-place' || args[a] === '.') {
+    inPlace = true;
+  } else if (args[a].indexOf('--') === 0) {
+    console.error('Unknown option: ' + args[a]);
+    printUsage();
+    process.exit(1);
+  } else {
+    positional.push(args[a]);
+  }
 }
 
-var targetDir = path.resolve(process.cwd(), projectName);
+var projectName;
+var targetDir;
 
-if (fs.existsSync(targetDir)) {
-  console.error('Error: Directory "' + projectName + '" already exists.');
-  process.exit(1);
+if (inPlace) {
+  targetDir = process.cwd();
+  projectName = positional[0] || path.basename(targetDir);
+} else {
+  projectName = positional[0];
+  if (!projectName) {
+    printUsage();
+    process.exit(1);
+  }
+  targetDir = path.resolve(process.cwd(), projectName);
+  if (fs.existsSync(targetDir)) {
+    console.error('Error: Directory "' + projectName + '" already exists.');
+    process.exit(1);
+  }
 }
 
-console.log('Creating FIAS plugin project: ' + projectName);
+console.log(
+  inPlace
+    ? 'Scaffolding FIAS plugin into current directory (' + projectName + ')'
+    : 'Creating FIAS plugin project: ' + projectName,
+);
 
-copyDir(TEMPLATE_DIR, targetDir, { name: projectName });
+copyDir(TEMPLATE_DIR, targetDir, { name: projectName }, { inPlace: inPlace, rootDest: targetDir });
 
-console.log('\nPlugin created at ./' + projectName + '\n');
+console.log('\nPlugin scaffolded.\n');
 console.log('Next steps:');
-console.log('  cd ' + projectName);
+if (!inPlace) {
+  console.log('  cd ' + projectName);
+}
 console.log('  npm install');
 console.log('  npx fias-dev login        # Authenticate with FIAS platform (opens browser)');
 console.log('  npm start                 # Start dev server + real AI harness (uses credits)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -2,7 +2,7 @@
 
 This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
 
-For other AI tool instruction files, see `AGENTS.md` (identical content).
+For other AI tool instruction files, see `CLAUDE.md` (identical content).
 
 ## Project Structure
 
@@ -268,6 +268,8 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 // Automatically persists to storage on change
 ```
 
+**Writes are debounced (SDK ≥ 1.8.0).** The in-memory value updates synchronously, but the underlying `storage_write` is coalesced (250 ms trailing-edge debounce, 1 s max-wait, flushed on unmount). Safe to call from `requestAnimationFrame` and other high-frequency handlers. For state that updates every frame (game positions, drag coordinates), still prefer plain `useState` — persisting transient state is wasteful and not useful on reload.
+
 ### `fias` — Imperative utilities
 
 ```tsx
@@ -317,9 +319,15 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 
 These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
 
+### Hitting a limit? Tell the user about Entity requests
+
+Don't just say "can't do that" when the user asks for something blocked by these rules — most often a direct external API call, a third-party service, or a capability the platform hasn't surfaced yet. The Fias team adds new **Entities** on request: platform-managed wrappers that hold credentials, handle auth, and expose the capability to plugins through `useEntityInvocation()` (or `useImageGeneration()` for image models). The plugin never bypasses the sandbox — it invokes the new Entity like any other model.
+
+When you hit a constraint, say so AND tell the user: file an Entity request on the Customer Support arche at `https://platform.fias.io/a/arche_customer_support`. Describe the service, endpoints, and auth method needed; once the Entity ships, the plugin can call it via `useEntityInvocation` with no sandbox change. Then propose a fallback that works inside the current sandbox (mock data, a simpler path, deferring the call) so the build keeps moving while the request is in flight.
+
 ### Sandboxing
 
-- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin"`
+- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin allow-downloads"`
 - **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
 - **No access** to parent DOM, cookies, or localStorage
 - **No external scripts or stylesheets** — everything must be bundled
@@ -338,6 +346,8 @@ These are hard limits enforced by the platform. Code that violates these will fa
 - `storage_read`: 300/minute
 - `storage_list`, `storage_delete`: 60/minute
 
+A separate **runaway-loop detector** fires if any method is called >50 times in 5 s and blocks that method for 10 s. Errors include the target, e.g. `Runaway loop detected: "storage_write" (path: __state/gameState) …` — the path tells you where to debounce at the source.
+
 ### Security Rules (enforced during review)
 
 - No `eval()`, `Function()`, `innerHTML`, or dynamic code execution
@@ -415,9 +425,17 @@ npx fias-dev validate
 ```bash
 npm run submit
 # Builds, validates, packages, uploads, submits for AI review
-# First listing: 5000 credits ($50). Re-submissions: 100 credits ($1).
 ```
 
+The first time you list a plugin in the marketplace there is a one-time
+listing fee; subsequent submissions of the same plugin only pay a small
+per-review fee. The harness fetches the exact amount from the server and
+shows it before you confirm — never assume a hardcoded price.
+
+If the AI review rejects your submission, the listing-fee portion is
+refunded automatically (the per-review portion is not, since review work
+happened either way).
+
 ## Common Patterns
 
 ### Theme-Aware Card Component

package/templates/default/CLAUDE.md

@@ -268,6 +268,8 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 // Automatically persists to storage on change
 ```
 
+**Writes are debounced (SDK ≥ 1.8.0).** The in-memory value updates synchronously, but the underlying `storage_write` is coalesced (250 ms trailing-edge debounce, 1 s max-wait, flushed on unmount). Safe to call from `requestAnimationFrame` and other high-frequency handlers. For state that updates every frame (game positions, drag coordinates), still prefer plain `useState` — persisting transient state is wasteful and not useful on reload.
+
 ### `fias` — Imperative utilities
 
 ```tsx
@@ -317,9 +319,15 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 
 These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
 
+### Hitting a limit? Tell the user about Entity requests
+
+Don't just say "can't do that" when the user asks for something blocked by these rules — most often a direct external API call, a third-party service, or a capability the platform hasn't surfaced yet. The Fias team adds new **Entities** on request: platform-managed wrappers that hold credentials, handle auth, and expose the capability to plugins through `useEntityInvocation()` (or `useImageGeneration()` for image models). The plugin never bypasses the sandbox — it invokes the new Entity like any other model.
+
+When you hit a constraint, say so AND tell the user: file an Entity request on the Customer Support arche at `https://platform.fias.io/a/arche_customer_support`. Describe the service, endpoints, and auth method needed; once the Entity ships, the plugin can call it via `useEntityInvocation` with no sandbox change. Then propose a fallback that works inside the current sandbox (mock data, a simpler path, deferring the call) so the build keeps moving while the request is in flight.
+
 ### Sandboxing
 
-- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin"`
+- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin allow-downloads"`
 - **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
 - **No access** to parent DOM, cookies, or localStorage
 - **No external scripts or stylesheets** — everything must be bundled
@@ -338,6 +346,8 @@ These are hard limits enforced by the platform. Code that violates these will fa
 - `storage_read`: 300/minute
 - `storage_list`, `storage_delete`: 60/minute
 
+A separate **runaway-loop detector** fires if any method is called >50 times in 5 s and blocks that method for 10 s. Errors include the target, e.g. `Runaway loop detected: "storage_write" (path: __state/gameState) …` — the path tells you where to debounce at the source.
+
 ### Security Rules (enforced during review)
 
 - No `eval()`, `Function()`, `innerHTML`, or dynamic code execution
@@ -415,9 +425,17 @@ npx fias-dev validate
 ```bash
 npm run submit
 # Builds, validates, packages, uploads, submits for AI review
-# First listing: 5000 credits ($50). Re-submissions: 100 credits ($1).
 ```
 
+The first time you list a plugin in the marketplace there is a one-time
+listing fee; subsequent submissions of the same plugin only pay a small
+per-review fee. The harness fetches the exact amount from the server and
+shows it before you confirm — never assume a hardcoded price.
+
+If the AI review rejects your submission, the listing-fee portion is
+refunded automatically (the per-review portion is not, since review work
+happened either way).
+
 ## Common Patterns
 
 ### Theme-Aware Card Component