@fiodos/cli 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Fiodos CLI — analyzes your app's source code and generates the in-app voice-agent manifest, then wires the orb. Powers `npx @fiodos/cli analyze`.",
   "type": "commonjs",
   "bin": {

package/src/aiAnalyze.js

@@ -76,7 +76,7 @@ AppManifest (all fields required unless noted):
     "requireConfirmation": boolean,
     "confirmationMessageTemplate": string (REQUIRED if requireConfirmation true),
     "parameters": { "<name>": {"type": "string"|"number"|"boolean", "required": boolean, "description": string (non-empty)} },
-    "contextRequirements": {"requiresVisibleContent"?: bool, "requiresAuth"?: bool} (optional),
+    "contextRequirements": {"requiresVisibleContent"?: bool, "requiresAuth"?: bool} (optional; set requiresAuth: true for actions that need a signed-in user — see the REQUIRES-AUTH rule below),
     "examples": string[] (3-4 natural voice phrases, REQUIRED non-empty)
   }],
   "policies": {"requireConfirmationForDestructive": true, "allowedWithoutAuth": string[], "contextRetentionTurns": 5}
@@ -164,6 +164,12 @@ ACTIONS: things a user could trigger by voice. ${actionHintLine} CRITICAL RULES:
 - Destructive/sensitive operations (delete data, logout, place/cancel orders, spend money) need requireConfirmation + confirmationMessageTemplate.
 - "parameters" only when the user must supply a value by voice.
 
+REQUIRES-AUTH — mark which actions need a signed-in user (set contextRequirements.requiresAuth):
+This drives a real safety gate: an action marked requiresAuth: true is NOT executed unless the host app reports the user is signed in, so the agent never attempts inside-the-app operations from a logged-out state (e.g. the user is on the login screen). Decide per action by reading the code:
+- Set requiresAuth: true for actions that only make sense for a signed-in user — i.e. anything that reads or changes data tied to a personal session/account: viewing or editing the user's own data, profile/settings, orders/cart history, balances, posting/saving content, in-app operations, or navigating-by-doing into private/authenticated areas. A strong signal: the handler reads a session/token/user id, calls an authenticated API, or lives behind an auth guard/middleware/redirect-to-login. If the app has a global auth gate (a root middleware/layout that redirects unauthenticated users), treat its inside-app actions as requiresAuth: true by default.
+- Leave requiresAuth false/absent for genuinely public actions that work with no session: public navigation, marketing/landing LINK actions (download/get-the-app, social links, contact/email/phone, pricing, legal, in-page anchors), changing language/theme, viewing openly public information, and the sign-in/sign-up flow itself.
+- Be conservative AND fail-safe: do not over-mark clearly public actions (that would needlessly block them when logged out), but when you genuinely cannot tell whether an action is public or requires a session, prefer requiresAuth: true — it is safer to ask the user to sign in than to attempt a private action without a session. requiresAuth never replaces requireConfirmation; an action can need both.
+
 THE MANUAL (description/preconditions/effect/relatedIntents per action; description per screen; appType/appFlow):
 This is the context the agent reads to understand the app, so it can reason instead of guessing. Derive every field from the REAL code:
 - description: what the action actually does (read the handler's body).
@@ -511,4 +517,14 @@ async function correctActionWiring({
   return { wiring, usage, costUSD };
 }
 
-module.exports = { analyzeWithAI, correctActionWiring, DEFAULT_MODEL, PRICES, resolveModel, isAnthropicModel };
+module.exports = {
+  analyzeWithAI,
+  correctActionWiring,
+  DEFAULT_MODEL,
+  PRICES,
+  resolveModel,
+  isAnthropicModel,
+  // Exported for offline tests of the analysis guidance (no API key needed).
+  buildSystemPrompt,
+  manifestSchemaDoc,
+};

package/src/index.js

@@ -629,11 +629,12 @@ async function main() {
           log: logUser,
           logDev,
         });
-        if (
-          envWriteResult &&
-          (envWriteResult.status === 'declined by user' || envWriteResult.status === 'manual')
-        ) {
-          printEnvManualReminder(envWriteResult.writePlan, { logUser, logDev });
+        // The reminder decides what to show: the local-env copy-paste block (only
+        // when the developer declined the local write) AND/OR the deploy-provider
+        // notice for the build-time public key (so the orb is never invisible in
+        // production for a missing var). No-ops when there is nothing to show.
+        if (envWriteResult) {
+          printEnvManualReminder(envWriteResult, { logUser, logDev });
         }
       } catch (e) {
         logDev(`[write-env] skipped: ${e.message}`);

package/src/writeEnv.js

@@ -1,10 +1,27 @@
 /**
- * writeEnv — consent-based API key / URL alignment for the app's environment.
+ * writeEnv — consent-based handling of the orb's environment variables.
  *
- * The orb must read the SAME key/URL the CLI published with. We always ASK
- * before writing (independent of --yes, which only skips orb/handler prompts).
- * If the developer declines, a copy-paste reminder is shown at the very END of
- * the run — after analysis, publish, orb mount and handler wiring are done.
+ * The orb must read the SAME key/URL the CLI published with. We always ASK before
+ * writing (independent of --yes, which only skips orb/handler prompts). Sensitive
+ * values follow ONE consistent flow:
+ *
+ *   1. Local env file  — "add it automatically, or add it yourself?" (yes/no).
+ *      · yes → written to the framework's env file, which we ALSO ensure is in
+ *              .gitignore so the secret never reaches GitHub.
+ *      · no  → a copy-paste reminder is shown at the very END of the run.
+ *   2. Deploy provider — for the build-time public key (VITE_/NEXT_PUBLIC_),
+ *      which is inlined at BUILD time: if it is only in the (gitignored,
+ *      never-pushed) local env and NOT in the provider, the production build
+ *      ships WITHOUT it and the orb never appears. A CLI cannot (and must not)
+ *      authenticate into the user's hosting account, so we do NOT prompt and we
+ *      do NOT touch their provider. Instead we DETECT the stack and print a
+ *      clear, numbered step-by-step at the END (copy key → paste in the
+ *      provider's env panel → redeploy) so they do it themselves, safely.
+ *
+ * SECURITY: no secret is ever hardcoded into committed source. The orb key
+ * (`fyd_…`) is a PUBLISHABLE client key (safe inside the frontend bundle), but it
+ * still must exist in the build environment — which is why it goes through env
+ * vars and the deploy-provider step, never into the repo.
  */
 'use strict';
 
@@ -63,6 +80,11 @@ function resolveEnvPlan(appRoot) {
   return { framework: null, file: null, candidates: [], keyVar: null, urlVar: null };
 }
 
+/** Frameworks whose public env vars are INLINED at build time (need provider env). */
+function isBuildTimePublicFramework(framework) {
+  return framework === 'vite' || framework === 'next';
+}
+
 function findEffectiveVar(appRoot, candidates, name) {
   for (const rel of candidates) {
     const filePath = path.join(appRoot, rel);
@@ -117,20 +139,78 @@ function askYesNo(question) {
   });
 }
 
+/** True if `.gitignore` already keeps `fileName` (or a glob covering it) out of git. */
 function isGitIgnored(appRoot, fileName) {
   const gi = path.join(appRoot, '.gitignore');
   if (!fs.existsSync(gi)) return false;
   try {
     const content = fs.readFileSync(gi, 'utf8');
-    const patterns = content.split('\n').map((l) => l.trim());
-    return patterns.some(
-      (p) => p === fileName || p === `/${fileName}` || p === '.env*' || p === '*.local' || p === '.env.local',
-    );
+    return gitignoreCovers(content, fileName);
   } catch {
     return false;
   }
 }
 
+/** Pure: does this .gitignore content keep `fileName` out of git? */
+function gitignoreCovers(content, fileName) {
+  const patterns = content.split('\n').map((l) => l.trim());
+  const glob = fileName.endsWith('.local') ? '*.local' : '.env*';
+  return patterns.some(
+    (p) =>
+      p === fileName ||
+      p === `/${fileName}` ||
+      p === '.env*' ||
+      p === '.env.*' ||
+      p === '*.local' ||
+      p === glob ||
+      p === fileName.replace(/^\.env/, '.env*'),
+  );
+}
+
+/**
+ * Guarantee the secret-bearing env file is git-ignored (never pushed to GitHub).
+ * Appends a covering pattern to `.gitignore` (creating it when absent) when the
+ * file is not already ignored. Idempotent. Returns what happened.
+ */
+function ensureEnvGitIgnored(appRoot, fileName) {
+  const gi = path.join(appRoot, '.gitignore');
+  const exists = fs.existsSync(gi);
+  let content = '';
+  try {
+    content = exists ? fs.readFileSync(gi, 'utf8') : '';
+  } catch {
+    content = '';
+  }
+  if (exists && gitignoreCovers(content, fileName)) {
+    return { changed: false, created: false, alreadyIgnored: true, pattern: null };
+  }
+  const pattern = fileName.endsWith('.local') ? '*.local' : fileName;
+  const header = '# Fiodos: keep local secrets out of git';
+  const prefix = content.length === 0 ? '' : content.endsWith('\n') ? '' : '\n';
+  const block = `${prefix}${content.length ? '\n' : ''}${header}\n${pattern}\n`;
+  try {
+    fs.writeFileSync(gi, content + block);
+    return { changed: true, created: !exists, alreadyIgnored: false, pattern };
+  } catch {
+    return { changed: false, created: false, alreadyIgnored: false, pattern, error: true };
+  }
+}
+
+/** Detect a deploy provider (and whether a Vercel project is already linked). */
+function detectDeployProvider(appRoot) {
+  const has = (rel) => fs.existsSync(path.join(appRoot, rel));
+  if (has('.vercel/project.json') || has('vercel.json')) {
+    return { provider: 'vercel', linked: has('.vercel/project.json') };
+  }
+  if (has('netlify.toml') || has('.netlify')) {
+    return { provider: 'netlify', linked: false };
+  }
+  if (has('wrangler.toml')) {
+    return { provider: 'cloudflare', linked: false };
+  }
+  return { provider: null, linked: false };
+}
+
 /**
  * Compute where the key/URL would go and what would change — no writes, no prompts.
  * @returns {object|null} null when there is nothing to do (already aligned / no key).
@@ -170,7 +250,7 @@ function computeEnvWritePlan(appRoot, apiKey, apiUrl, defaultApiUrl) {
   const urlOk = !urlNeedsFix && (wantUrl ? currentUrl === wantUrl : true);
 
   if (keyMatches && urlOk) {
-    return { kind: 'aligned', targetRel, plan };
+    return { kind: 'aligned', targetRel, plan, framework: plan.framework, keyVar: plan.keyVar, apiKey };
   }
 
   const envLines = [`${plan.keyVar}=${apiKey}`];
@@ -180,6 +260,9 @@ function computeEnvWritePlan(appRoot, apiKey, apiUrl, defaultApiUrl) {
   return {
     kind: 'writable',
     plan,
+    framework: plan.framework,
+    keyVar: plan.keyVar,
+    urlVar: plan.urlVar,
     targetRel,
     absPath: path.join(appRoot, targetRel),
     envLines,
@@ -194,50 +277,107 @@ function computeEnvWritePlan(appRoot, apiKey, apiUrl, defaultApiUrl) {
   };
 }
 
-/** Branded reminder shown at the END when the developer declined the write. */
-function printEnvManualReminder(writePlan, { logUser, logDev }) {
-  if (!writePlan || writePlan.kind === 'aligned') return;
-
-  logUser('Add your API key to your environment file (last step)');
+/** Where, per provider, the Environment Variables panel lives + how to redeploy. */
+function providerEnvHint(provider) {
+  if (provider === 'vercel') {
+    return {
+      label: 'Vercel',
+      where: 'Project → Settings → Environment Variables (tick Production, Preview, Development)',
+      redeploy: 'Deployments → ⋯ → Redeploy (or push a new commit)',
+    };
+  }
+  if (provider === 'netlify') {
+    return {
+      label: 'Netlify',
+      where: 'Site configuration → Environment variables → Add a variable',
+      redeploy: 'Deploys → Trigger deploy → Deploy site',
+    };
+  }
+  if (provider === 'cloudflare') {
+    return {
+      label: 'Cloudflare Pages',
+      where: 'Workers & Pages → your project → Settings → Variables and Secrets',
+      redeploy: 'Deployments → Retry deployment (or push a new commit)',
+    };
+  }
+  return null;
+}
 
-  if (writePlan.kind === 'manual-angular') {
-    console.log(
-      `  Angular: open ${writePlan.file} and set fyodosApiKey / fyodosApiUrl:`,
-    );
-    console.log(`    fyodosApiKey: '${writePlan.apiKey}'`);
-    console.log(`    fyodosApiUrl: '${writePlan.apiUrl}'`);
-    return;
+/**
+ * Clear, numbered step-by-step for setting the build-time public key in the
+ * deploy provider. Step 2 always speaks generically ("your hosting provider");
+ * when we detect a provider we append an optional tip in parentheses — we never
+ * assume the user's host is Vercel/Netlify/etc.
+ */
+function deployReminderLines(deploy) {
+  const { keyVar, apiKey, provider } = deploy;
+  const hint = providerEnvHint(provider);
+  const lines = [];
+  lines.push('  Step 1 — Copy your orb key (this exact value):');
+  lines.push(`            ${apiKey}`);
+  lines.push('');
+  lines.push('  Step 2 — In your hosting provider, open Environment Variables and add:');
+  lines.push(`            Name:  ${keyVar}`);
+  lines.push(`            Value: ${apiKey}`);
+  if (hint) {
+    lines.push(`            (e.g. ${hint.label}: ${hint.where})`);
+  } else {
+    lines.push('            (usually Project or Site → Settings → Environment Variables)');
   }
+  lines.push('');
+  lines.push('  Step 3 — Redeploy so the variable is built in:');
+  lines.push(`            ${hint ? hint.redeploy : 'Trigger a new deploy (or push a commit)'}`);
+  return lines;
+}
 
-  if (writePlan.kind === 'manual-unknown') {
-    console.log('  Add to your project .env (use NEXT_PUBLIC_ for Next, VITE_ for Vite):');
-    console.log(`    ${writePlan.keyVar}=${writePlan.apiKey}`);
-    if (writePlan.apiUrl && writePlan.apiUrl !== 'https://api.fyodos.com') {
-      console.log(`    ${writePlan.urlVar}=${writePlan.apiUrl}`);
+/** Branded reminder shown at the END (declined local write and/or deploy step). */
+function printEnvManualReminder(result, { logUser, logDev }) {
+  if (!result) return;
+  const writePlan = result.writePlan || (result.kind ? result : null);
+  const deploy = result.deploy || null;
+  const declinedLocal =
+    result.status === 'declined by user' || result.status === 'manual';
+
+  if (writePlan && writePlan.kind !== 'aligned' && declinedLocal) {
+    logUser('Add your API key to your environment file (last step)');
+
+    if (writePlan.kind === 'manual-angular') {
+      console.log(`  Angular: open ${writePlan.file} and set fyodosApiKey / fyodosApiUrl:`);
+      console.log(`    fyodosApiKey: '${writePlan.apiKey}'`);
+      console.log(`    fyodosApiUrl: '${writePlan.apiUrl}'`);
+    } else if (writePlan.kind === 'manual-unknown') {
+      console.log('  Add to your project .env (use NEXT_PUBLIC_ for Next, VITE_ for Vite):');
+      console.log(`    ${writePlan.keyVar}=${writePlan.apiKey}`);
+      if (writePlan.apiUrl && writePlan.apiUrl !== 'https://api.fyodos.com') {
+        console.log(`    ${writePlan.urlVar}=${writePlan.apiUrl}`);
+      }
+    } else {
+      console.log(`  File: ${writePlan.absPath}`);
+      console.log('  Add these lines:');
+      for (const line of writePlan.envLines) console.log(`    ${line}`);
     }
-    return;
+    if (logDev) logDev(`[write-env] manual reminder for ${writePlan.targetRel || writePlan.file || 'env'}`);
   }
 
-  const rel = writePlan.targetRel;
-  const displayPath = writePlan.absPath;
-  console.log(`  File: ${displayPath}`);
-  console.log('  Add these lines:');
-  for (const line of writePlan.envLines) {
-    console.log(`    ${line}`);
+  if (deploy && deploy.reminder) {
+    logUser('Make the orb appear in PRODUCTION — add the key to your host (3 steps)');
+    for (const line of deployReminderLines(deploy)) console.log(line ? `  ${line}` : '');
+    if (logDev) logDev(`[write-env] deploy reminder for provider=${deploy.provider || 'unknown'}`);
   }
-  logDev(`[write-env] manual reminder for ${rel}`);
 }
 
 /**
- * Ask consent and optionally write. Returns { status, writePlan }.
+ * Ask consent and optionally write. Returns { status, writePlan, deploy }.
  * `assumeYes` comes from --write-env-yes only (NOT global --yes).
  */
 async function offerWriteEnv({ appRoot, apiKey, apiUrl, defaultApiUrl, assumeYes, log, logDev: devLog }) {
   const writePlan = computeEnvWritePlan(appRoot, apiKey, apiUrl, defaultApiUrl);
-  if (!writePlan) return { status: 'skipped (no API key)', writePlan: null };
+  if (!writePlan) return { status: 'skipped (no API key)', writePlan: null, deploy: null };
   if (writePlan.kind === 'aligned') {
     log(`Your environment already uses the same API key as this project. Nothing to change.`);
-    return { status: 'already aligned', writePlan };
+    // Even when the local env is aligned, production may still be missing the key.
+    const deploy = planDeployReminder(appRoot, writePlan);
+    return { status: 'already aligned', writePlan, deploy };
   }
 
   const targetLabel =
@@ -249,18 +389,18 @@ async function offerWriteEnv({ appRoot, apiKey, apiUrl, defaultApiUrl, assumeYes
 
   let proceed = assumeYes;
   if (!proceed) {
-    proceed = await askYesNo(
-      `◉ Fiodos · Add your API key to ${targetLabel}? [yes/no] `,
-    );
+    proceed = await askYesNo(`◉ Fiodos · Add your API key to ${targetLabel}? [yes/no] `);
   }
 
   if (!proceed) {
-    return { status: 'declined by user', writePlan };
+    const deploy = planDeployReminder(appRoot, writePlan);
+    return { status: 'declined by user', writePlan, deploy };
   }
 
   if (writePlan.kind === 'manual-angular' || writePlan.kind === 'manual-unknown') {
     log('Could not write automatically for this framework — see the reminder at the end.');
-    return { status: 'manual', writePlan };
+    const deploy = planDeployReminder(appRoot, writePlan);
+    return { status: 'manual', writePlan, deploy };
   }
 
   const { plan, targetRel, keyMatches, wantUrl, urlNeedsFix, apiKey: key, apiUrl: url } = writePlan;
@@ -279,10 +419,40 @@ async function offerWriteEnv({ appRoot, apiKey, apiUrl, defaultApiUrl, assumeYes
   fs.writeFileSync(filePath, `${out.join('\n')}\n`);
   log(`API key saved to ${targetRel}.`);
 
-  if (!isGitIgnored(appRoot, targetRel)) {
-    devLog(`Reminder: add ${targetRel} to .gitignore so you don't commit your API key.`);
+  // SECURITY: guarantee the secret-bearing file is git-ignored (never pushed).
+  const gi = ensureEnvGitIgnored(appRoot, targetRel);
+  if (gi.changed) {
+    log(`Added ${gi.pattern} to .gitignore so your key is never pushed to GitHub.`);
+  } else if (gi.alreadyIgnored) {
+    if (devLog) devLog(`[write-env] ${targetRel} already covered by .gitignore`);
+  } else if (gi.error) {
+    log(`Heads up: could not update .gitignore — make sure ${targetRel} is git-ignored.`);
+  }
+
+  const deploy = planDeployReminder(appRoot, writePlan);
+  return { status: 'written', writePlan, deploy };
+}
+
+/**
+ * Plan the deploy-provider reminder for the build-time PUBLIC key
+ * (VITE_/NEXT_PUBLIC_). We do NOT prompt and we do NOT touch the user's hosting
+ * provider — a CLI cannot safely authenticate into someone's Vercel/Netlify
+ * account, and we never want to access a production provider on their behalf.
+ *
+ * Instead we DETECT the stack (provider + var name) and queue a clear, numbered
+ * step-by-step that is printed at the very end of the run (see
+ * `deployReminderLines`). The developer copies the key and pastes it into their
+ * provider's Environment Variables panel themselves, then redeploys.
+ */
+function planDeployReminder(appRoot, writePlan) {
+  const framework = writePlan.framework;
+  const keyVar = writePlan.keyVar;
+  const apiKey = writePlan.apiKey;
+  if (!apiKey || !keyVar || !isBuildTimePublicFramework(framework)) {
+    return null; // Angular / unknown handle their own manual reminders.
   }
-  return { status: 'written', writePlan };
+  const det = detectDeployProvider(appRoot);
+  return { provider: det.provider, linked: det.linked, keyVar, apiKey, reminder: true };
 }
 
 module.exports = {
@@ -290,4 +460,9 @@ module.exports = {
   resolveEnvPlan,
   computeEnvWritePlan,
   printEnvManualReminder,
+  ensureEnvGitIgnored,
+  gitignoreCovers,
+  detectDeployProvider,
+  isBuildTimePublicFramework,
+  deployReminderLines,
 };