@fias/create-fias-plugin 1.1.3 → 1.2.0

package/index.js

@@ -4,9 +4,97 @@
 
 var fs = require('fs');
 var path = require('path');
+var childProcess = require('child_process');
 
 var TEMPLATE_DIR = path.resolve(__dirname, 'templates/default');
 
+// =============================================================================
+// Self-update on stale npx cache.
+//
+// Failure mode this guards against: a developer who has scaffolded a FIAS
+// plugin once before has `@fias/create-fias-plugin` in their npx cache
+// (`~/.npm/_npx/<hash>/`). Subsequent `npm create @fias/fias-plugin <name>`
+// invocations reuse the cached binary WITHOUT checking the npm registry for
+// a newer version. Result: the CLAUDE.md / AGENTS.md / templates dropped
+// into their new project are months out of date, and an AI assistant
+// reading those files designs against an obsolete SDK surface (we hit this
+// concretely in May 2026 — a fresh scaffold's CLAUDE.md was missing the
+// in-app-purchase hook, vault documents, asset library, and the
+// `store:purchase` permission, even though all four had been live on npm
+// for weeks).
+//
+// Fix: at startup, hit the registry for the latest published version. If
+// our running version is older, transparently re-exec the latest via npx
+// (which downloads it on the fly) with the same args, then exit. A
+// `_FIAS_CREATE_REEXEC=1` env marker prevents infinite recursion when the
+// freshly-installed copy starts and re-runs this same check.
+//
+// Any failure of the check (offline, npm slow, registry 503, ...) falls
+// through silently to the cached version. Scaffolding a slightly-old
+// plugin is strictly better than blocking the user on a network hiccup.
+// =============================================================================
+
+var SELF_NAME = '@fias/create-fias-plugin';
+var REEXEC_GUARD = '_FIAS_CREATE_REEXEC';
+
+function compareSemver(a, b) {
+  // Returns 1 if a > b, -1 if a < b, 0 if equal. Plain x.y.z; pre-release
+  // suffixes ignored (we never publish pre-releases of this scaffold).
+  var pa = a.split('.').map(function (s) {
+    return parseInt(s, 10) || 0;
+  });
+  var pb = b.split('.').map(function (s) {
+    return parseInt(s, 10) || 0;
+  });
+  for (var i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+function maybeReexecLatest() {
+  if (process.env[REEXEC_GUARD] === '1') return;
+
+  var currentVersion = require('./package.json').version;
+
+  // 5s timeout so a slow/offline network doesn't make scaffolding hang.
+  var view = childProcess.spawnSync('npm', ['view', SELF_NAME, 'version'], {
+    encoding: 'utf-8',
+    timeout: 5000,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (view.status !== 0 || !view.stdout) return;
+
+  var latest = view.stdout.trim();
+  if (!latest || compareSemver(latest, currentVersion) <= 0) return;
+
+  console.log(
+    '[create-fias-plugin] cached version ' +
+      currentVersion +
+      ' is stale; using latest ' +
+      latest +
+      ' from npm\n',
+  );
+
+  var env = Object.assign({}, process.env);
+  env[REEXEC_GUARD] = '1';
+
+  var rerun = childProcess.spawnSync(
+    'npx',
+    ['--yes', SELF_NAME + '@' + latest].concat(process.argv.slice(2)),
+    { stdio: 'inherit', env: env },
+  );
+  process.exit(rerun.status == null ? 1 : rerun.status);
+}
+
+try {
+  maybeReexecLatest();
+} catch (_e) {
+  // Any unexpected error: fall through to the cached version. Don't block
+  // the user on a self-update-check failure.
+}
+
 function copyDir(src, dest, replacements, opts) {
   fs.mkdirSync(dest, { recursive: true });
 

package/package.json

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

package/templates/default/AGENTS.md

@@ -499,6 +499,7 @@ navigateTo('/settings');
 
 ### `useStepNavigation()` — Multi-step workflows
 
+**Permission:** None for in-memory use; `storage:sandbox` when `persistKey` is set (it reads/writes `__state/<persistKey>` via the storage bridge).
 **Returns:** `StepNavigationApi`
 
 ```tsx
@@ -780,6 +781,44 @@ 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).
 
+### Managing the asset library (for `useArcheAssets`)
+
+`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <staging|prod|local>` (default `staging`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
+
+```bash
+npx fias-dev assets enable                  # Turn on the asset library for this arche
+npx fias-dev assets status                  # Quota usage + billing summary
+npx fias-dev assets upload <dir>            # Bulk-upload images; subfolder name → default tag
+                                            # Flags: --concurrency <1-16>, --dry-run
+npx fias-dev assets list                    # List assets; --tag <tag>, --limit <1-100>
+npx fias-dev assets tag <assetId> --add <t> # Add or remove tags; --remove <t> also supported
+npx fias-dev assets delete <assetId>        # Soft-delete (excluded from future publishes); -y to skip confirm
+npx fias-dev assets disable                 # Turn off the asset library
+```
+
+Uploads stage into the contributor's draft set; they only become visible to plugin runtimes after the next `npm run submit` publishes a new arche version. Existing published versions keep their original frozen snapshot.
+
+### Managing collaborators
+
+Multi-developer plugins use `arche_collaborators` for operational ownership (publishing, team management) — distinct from financial ownership (`contributor_id`, which is immutable in v1). Every arche must keep ≥1 active owner; revokes that would drop to zero return `MUST_KEEP_ONE_OWNER`.
+
+```bash
+npx fias-dev collaborators list                            # List active collaborators
+npx fias-dev collaborators add <email|username|userId> \   # Default role: publisher
+    --role <owner|publisher|viewer> --expires <iso>        # Owners cannot have expiry
+npx fias-dev collaborators set <identifier> \              # Change role and/or expiry
+    --role <role> --expires <iso>                          # --no-expires clears expiry
+npx fias-dev collaborators remove <identifier>             # Revoke a collaborator
+```
+
+All commands accept `--env <staging|production|local>` (default `staging`).
+
+### Other CLI diagnostics
+
+```bash
+npx fias-dev check-auth                # Print per-environment auth status (which envs have saved keys)
+```
+
 ## Common Patterns
 
 ### Theme-Aware Card Component

package/templates/default/CLAUDE.md

@@ -499,6 +499,7 @@ navigateTo('/settings');
 
 ### `useStepNavigation()` — Multi-step workflows
 
+**Permission:** None for in-memory use; `storage:sandbox` when `persistKey` is set (it reads/writes `__state/<persistKey>` via the storage bridge).
 **Returns:** `StepNavigationApi`
 
 ```tsx
@@ -780,6 +781,44 @@ 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).
 
+### Managing the asset library (for `useArcheAssets`)
+
+`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <staging|prod|local>` (default `staging`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
+
+```bash
+npx fias-dev assets enable                  # Turn on the asset library for this arche
+npx fias-dev assets status                  # Quota usage + billing summary
+npx fias-dev assets upload <dir>            # Bulk-upload images; subfolder name → default tag
+                                            # Flags: --concurrency <1-16>, --dry-run
+npx fias-dev assets list                    # List assets; --tag <tag>, --limit <1-100>
+npx fias-dev assets tag <assetId> --add <t> # Add or remove tags; --remove <t> also supported
+npx fias-dev assets delete <assetId>        # Soft-delete (excluded from future publishes); -y to skip confirm
+npx fias-dev assets disable                 # Turn off the asset library
+```
+
+Uploads stage into the contributor's draft set; they only become visible to plugin runtimes after the next `npm run submit` publishes a new arche version. Existing published versions keep their original frozen snapshot.
+
+### Managing collaborators
+
+Multi-developer plugins use `arche_collaborators` for operational ownership (publishing, team management) — distinct from financial ownership (`contributor_id`, which is immutable in v1). Every arche must keep ≥1 active owner; revokes that would drop to zero return `MUST_KEEP_ONE_OWNER`.
+
+```bash
+npx fias-dev collaborators list                            # List active collaborators
+npx fias-dev collaborators add <email|username|userId> \   # Default role: publisher
+    --role <owner|publisher|viewer> --expires <iso>        # Owners cannot have expiry
+npx fias-dev collaborators set <identifier> \              # Change role and/or expiry
+    --role <role> --expires <iso>                          # --no-expires clears expiry
+npx fias-dev collaborators remove <identifier>             # Revoke a collaborator
+```
+
+All commands accept `--env <staging|production|local>` (default `staging`).
+
+### Other CLI diagnostics
+
+```bash
+npx fias-dev check-auth                # Print per-environment auth status (which envs have saved keys)
+```
+
 ## Common Patterns
 
 ### Theme-Aware Card Component