@paradigma-inc/flywheel 0.1.104 → 0.1.108

package/README.md

@@ -14,6 +14,12 @@ One-shot installer (macOS and Linux):
 curl -fsSL https://flywheel.paradigma.inc/install | sh
 ```
 
+Windows users running their AI coding host from WSL should open the WSL distro,
+install Node.js 20+ and npm inside WSL, and run the same installer there.
+Flywheel then writes WSL-side config, so launch the host from that same WSL
+environment. If browser auth does not open from WSL, copy the printed approval
+URL and setup code into your Windows browser.
+
 The script installs `@paradigma-inc/flywheel@latest` into the managed user
 prefix `${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}`, adds a marked PATH block
 when needed, and then runs guided `flywheel setup` through the installed binary.
@@ -47,9 +53,17 @@ if (($userPath -split ";") -notcontains $prefix) {
 if (($env:Path -split ";") -notcontains $prefix) {
   $env:Path = "$prefix;$env:Path"
 }
-& "$prefix\flywheel.cmd" setup --mode cli
+
+# MCP host wiring for native Windows hosts
+& "$prefix\flywheel.cmd" setup --mode mcp
 ```
 
+Use the PowerShell path when Codex, Claude Code, Cursor, or another AI coding
+host runs as a native Windows process. Use `--mode cli` instead when you only
+want direct `flywheel` binary setup without MCP host wiring. Do not install in
+both WSL and native Windows unless you intentionally want separate Flywheel
+setups.
+
 Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 
 ```bash
@@ -57,6 +71,12 @@ Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
 ```
 
+In native PowerShell, the equivalent command is:
+
+```powershell
+npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
+```
+
 ## Shell Completion
 
 `flywheel completion <shell>` generates shell completion scripts from the public
@@ -200,12 +220,15 @@ npx --yes @paradigma-inc/flywheel setup --mode cli
 
 ## Auth Modes And Remote Shells
 
-`setup --auth-mode auto|loopback|device` controls authentication behavior:
+`setup --auth-mode <mode>` controls authentication behavior. Supported values
+are:
 
-- `loopback`: opens `/auth/mcp/setup` and waits for a localhost callback.
+- `auto` (default): uses the active device approval flow.
 - `device`: opens `/auth/mcp/setup/device`, confirms a setup code in browser,
   and CLI polls for approval.
-- `auto` (default): uses `device` on SSH shells and `loopback` otherwise.
+- `loopback`: retired legacy mode. The parser still accepts it so explicit
+  requests receive the deterministic FLY-416 remediation, which tells users to
+  use `--auth-mode device` or `--auth-mode auto`.
 
 Remote/headless example:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.104",
+  "version": "0.1.108",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [

package/src/cli.mjs

@@ -1369,7 +1369,8 @@ Configure the Flywheel CLI, MCP host entries, and bundled skills without changin
     .optionsGroup("Advanced:")
     .option(
       "--auth-mode <mode>",
-      "API-key mint flow: auto | loopback | device (default: auto)",
+      "Device approval flow; default auto. " +
+        "Explicit loopback is retired and returns FLY-416 guidance",
       normalizeAuthMode,
       "auto",
     )

package/src/mcp-writer.mjs

@@ -1,6 +1,6 @@
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
+import { access, readFile } from "node:fs/promises";
 import { load as loadYaml, dump as dumpYaml } from "js-yaml";
+import { secureFileMode, writeSecureFile } from "./secure-write.mjs";
 
 function stripJsonComments(text) {
   let result = "";
@@ -117,11 +117,7 @@ export async function readJsonConfig(filePath) {
 }
 
 export async function writeJsonConfig(filePath, config) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`, {
-    encoding: "utf8",
-    mode: 0o600,
-  });
+  await writeSecureFile(filePath, `${JSON.stringify(config, null, 2)}\n`);
 }
 
 export async function readYamlConfig(filePath) {
@@ -146,11 +142,7 @@ export async function readYamlConfig(filePath) {
 }
 
 export async function writeYamlConfig(filePath, config) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, dumpYaml(config, { noRefs: true }), {
-    encoding: "utf8",
-    mode: 0o600,
-  });
+  await writeSecureFile(filePath, dumpYaml(config, { noRefs: true }));
 }
 
 export async function resolveMcpPath(candidates) {
@@ -479,6 +471,7 @@ export async function appendTomlServer(
     // header when the caller explicitly toggled auth mode via `--oauth` or
     // `--api-key`.
     if (!enforceAuthMode || existingEntry.authMode === newAuthMode) {
+      await secureFileMode(filePath);
       return { alreadyExists: true };
     }
   }
@@ -515,11 +508,7 @@ export async function appendTomlServer(
       : existing.length > 0
         ? "\n"
         : "";
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, `${existing}${separator}${block}`, {
-    encoding: "utf8",
-    mode: 0o600,
-  });
+  await writeSecureFile(filePath, `${existing}${separator}${block}`);
   return { alreadyExists: false };
 }
 
@@ -582,7 +571,6 @@ export async function removeCodexTomlServer({ filePath, serverName }) {
   });
   if (!removed) return { changed: false };
 
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, stripped, { encoding: "utf8", mode: 0o600 });
+  await writeSecureFile(filePath, stripped);
   return { changed: true };
 }

package/src/public-command-metadata.mjs

@@ -296,7 +296,8 @@ export const USAGE_EXTRAS = [
         name: "auth-mode",
         type: "string",
         usage: "--auth-mode <MODE>",
-        description: "API-key mint flow: auto | loopback | device",
+        description:
+          "Device approval flow; retired legacy mode returns FLY-416 guidance; default auto",
         default: "auto",
         choices: ["auto", "loopback", "device"],
       },

package/src/runtime/runtime-config.mjs

@@ -1,6 +1,7 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { writeSecureFile } from "../secure-write.mjs";
 
 const RUNTIME_BASE_URL_SUFFIX = "/api";
 
@@ -76,9 +77,8 @@ export async function writeRuntimeConfig({
   }
 
   const baseUrl = normalizeRuntimeBaseUrl(origin);
-  await mkdir(path.dirname(configPath), { recursive: true });
   const existing = await readExistingRuntimeConfig(configPath);
   const merged = { ...existing, baseUrl, apiKey: trimmedKey };
-  await writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  await writeSecureFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
   return { configPath, baseUrl };
 }

package/src/runtime/vendor/flywheel-cli-dist/generatedProductTelemetryContract.d.ts

@@ -1,9 +1,9 @@
 export declare const PRODUCT_TELEMETRY_CONTRACT_VERSION: "2026-05-18.2";
-export declare const PRODUCT_TELEMETRY_EVENT_NAMES: readonly ["api_client_operation_recorded", "api_route_behavior_recorded", "cli_command_behavior_recorded", "credits_checkout_started", "mcp_tool_behavior_recorded", "message_sent", "node_created", "node_link_disabled", "node_link_enabled", "node_public_disabled", "node_public_enabled", "product_demand_signal_recorded", "server_workflow_behavior_recorded", "subscription_checkout_started", "user_session_started", "web_app_opened", "web_artifact_payload_batch", "web_artifact_payload_failed", "web_artifact_payload_loaded", "web_artifact_payload_retried", "web_artifact_section_opened", "web_artifact_unrenderable_seen", "web_asset_deleted", "web_asset_note_saved", "web_asset_operation_failed", "web_asset_panel_opened", "web_asset_uploaded", "web_collaboration_action_completed", "web_collaboration_action_failed", "web_graph_layout_changed", "web_graph_load_failed", "web_graph_loaded", "web_graph_mutation_completed", "web_graph_mutation_failed", "web_graph_mutation_started", "web_graph_node_focused", "web_graph_opened", "web_graph_partial_notice_shown", "web_graph_search_changed", "web_graph_search_empty", "web_node_closed", "web_node_edit_cancelled", "web_node_edit_failed", "web_node_edit_saved", "web_node_edit_started", "web_node_hydration_completed", "web_node_hydration_failed", "web_node_lease_acquired", "web_node_lease_failed", "web_node_lease_heartbeat_failed", "web_node_lease_released", "web_node_opened", "web_node_stage_committed", "web_node_stage_created", "web_node_stage_discarded", "web_node_stage_failed", "web_node_stage_rebased", "web_settings_opened", "web_temp_node_commit_completed", "web_temp_node_commit_failed"];
+export declare const PRODUCT_TELEMETRY_EVENT_NAMES: readonly ["api_client_operation_recorded", "api_route_behavior_recorded", "cli_command_behavior_recorded", "credits_checkout_started", "mcp_tool_behavior_recorded", "message_sent", "node_created", "node_link_disabled", "node_link_enabled", "node_public_disabled", "node_public_enabled", "product_demand_signal_recorded", "server_workflow_behavior_recorded", "subscription_checkout_started", "user_session_started", "web_app_opened", "web_artifact_payload_batch", "web_artifact_payload_failed", "web_artifact_payload_loaded", "web_artifact_payload_retried", "web_artifact_section_opened", "web_artifact_unrenderable_seen", "web_asset_deleted", "web_asset_note_saved", "web_asset_operation_failed", "web_asset_panel_opened", "web_asset_uploaded", "web_collaboration_action_completed", "web_collaboration_action_failed", "web_graph_filter_panel_closed", "web_graph_filter_panel_opened", "web_graph_filter_visibility_changed", "web_graph_layout_changed", "web_graph_load_failed", "web_graph_loaded", "web_graph_mutation_completed", "web_graph_mutation_failed", "web_graph_mutation_started", "web_graph_node_focused", "web_graph_opened", "web_graph_partial_notice_shown", "web_graph_search_changed", "web_graph_search_empty", "web_node_closed", "web_node_edit_cancelled", "web_node_edit_failed", "web_node_edit_saved", "web_node_edit_started", "web_node_hydration_completed", "web_node_hydration_failed", "web_node_lease_acquired", "web_node_lease_failed", "web_node_lease_heartbeat_failed", "web_node_lease_released", "web_node_opened", "web_node_stage_committed", "web_node_stage_created", "web_node_stage_discarded", "web_node_stage_failed", "web_node_stage_rebased", "web_settings_opened", "web_temp_node_commit_completed", "web_temp_node_commit_failed"];
 export type ProductTelemetryEventName = (typeof PRODUCT_TELEMETRY_EVENT_NAMES)[number];
 export declare const PRODUCT_TELEMETRY_SURFACES: readonly ["api", "api_client", "cli", "mcp", "server", "webui"];
 export type ProductTelemetrySurface = (typeof PRODUCT_TELEMETRY_SURFACES)[number];
-export declare const WEBUI_PRODUCT_TELEMETRY_EVENT_NAMES: readonly ["web_app_opened", "web_artifact_payload_batch", "web_artifact_payload_failed", "web_artifact_payload_loaded", "web_artifact_payload_retried", "web_artifact_section_opened", "web_artifact_unrenderable_seen", "web_asset_deleted", "web_asset_note_saved", "web_asset_operation_failed", "web_asset_panel_opened", "web_asset_uploaded", "web_collaboration_action_completed", "web_collaboration_action_failed", "web_graph_layout_changed", "web_graph_load_failed", "web_graph_loaded", "web_graph_mutation_completed", "web_graph_mutation_failed", "web_graph_mutation_started", "web_graph_node_focused", "web_graph_opened", "web_graph_partial_notice_shown", "web_graph_search_changed", "web_graph_search_empty", "web_node_closed", "web_node_edit_cancelled", "web_node_edit_failed", "web_node_edit_saved", "web_node_edit_started", "web_node_hydration_completed", "web_node_hydration_failed", "web_node_lease_acquired", "web_node_lease_failed", "web_node_lease_heartbeat_failed", "web_node_lease_released", "web_node_opened", "web_node_stage_committed", "web_node_stage_created", "web_node_stage_discarded", "web_node_stage_failed", "web_node_stage_rebased", "web_settings_opened", "web_temp_node_commit_completed", "web_temp_node_commit_failed"];
+export declare const WEBUI_PRODUCT_TELEMETRY_EVENT_NAMES: readonly ["web_app_opened", "web_artifact_payload_batch", "web_artifact_payload_failed", "web_artifact_payload_loaded", "web_artifact_payload_retried", "web_artifact_section_opened", "web_artifact_unrenderable_seen", "web_asset_deleted", "web_asset_note_saved", "web_asset_operation_failed", "web_asset_panel_opened", "web_asset_uploaded", "web_collaboration_action_completed", "web_collaboration_action_failed", "web_graph_filter_panel_closed", "web_graph_filter_panel_opened", "web_graph_filter_visibility_changed", "web_graph_layout_changed", "web_graph_load_failed", "web_graph_loaded", "web_graph_mutation_completed", "web_graph_mutation_failed", "web_graph_mutation_started", "web_graph_node_focused", "web_graph_opened", "web_graph_partial_notice_shown", "web_graph_search_changed", "web_graph_search_empty", "web_node_closed", "web_node_edit_cancelled", "web_node_edit_failed", "web_node_edit_saved", "web_node_edit_started", "web_node_hydration_completed", "web_node_hydration_failed", "web_node_lease_acquired", "web_node_lease_failed", "web_node_lease_heartbeat_failed", "web_node_lease_released", "web_node_opened", "web_node_stage_committed", "web_node_stage_created", "web_node_stage_discarded", "web_node_stage_failed", "web_node_stage_rebased", "web_settings_opened", "web_temp_node_commit_completed", "web_temp_node_commit_failed"];
 export type WebuiProductTelemetryEventName = (typeof WEBUI_PRODUCT_TELEMETRY_EVENT_NAMES)[number];
 export declare const WEBUI_NODE_WORKFLOW_FAMILIES: readonly ["artifacts", "assets", "bulk_graph_actions", "canvas", "commit", "context_menu", "graph_layout", "hooks", "lease", "minimap", "node_focus", "node_hydration", "node_open", "node_selection", "node_view_editing", "partial_graph_preview", "radial_view", "share_policy", "staged_edit", "tags", "timeline_layout"];
 export type WebuiNodeWorkflowFamily = (typeof WEBUI_NODE_WORKFLOW_FAMILIES)[number];