@paradigma-inc/flywheel 0.1.74 → 0.1.78

package/README.md

@@ -57,6 +57,35 @@ Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
 ```
 
+## Shell Completion
+
+`flywheel completion <shell>` generates shell completion scripts from the public
+Flywheel command spec. It requires the official `usage` executable on `PATH`;
+install it with one of:
+
+```bash
+mise use -g usage
+brew install usage
+cargo install usage-cli
+cargo binstall usage-cli
+pacman -S usage
+```
+
+Generate the script for your shell and redirect it wherever your shell setup
+loads completions:
+
+```bash
+flywheel completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/flywheel
+flywheel completion zsh > ~/.zsh/completions/_flywheel
+flywheel completion fish > ~/.config/fish/completions/flywheel.fish
+flywheel completion powershell > flywheel.ps1
+flywheel completion nu > ~/.config/nushell/autoload/flywheel.nu
+flywheel completion nushell > ~/.config/nushell/autoload/flywheel.nu
+```
+
+This command generates scripts only. It does not install completions. It does
+nothing to shell startup files and does not edit shell profiles.
+
 ## Uninstall
 
 One-shot uninstaller (macOS and Linux):

package/package.json

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

package/skills/flywheel/references/flywheel-mcp-tool-map.md

@@ -93,7 +93,8 @@ Hook workflow-if contract (first version):
 - Workflow-if operators: `all`, `any`, `not`, `event`, `any_artifact`; predicate operators: `eq`, `in`, `exists`.
 - Canonical none-artifact expression: `not: { any_artifact: ... }`.
 - Run cardinality is fixed at one run per `(hook_id, event_id)` (no artifact fanout).
-- Submission-only matching is typically `any_artifact.field=metadata.role` with `eq: submission`.
+- Submission-only matching is typically `any_artifact.field=metadata.campaign_role` with `eq: submission`.
+- Campaign submission artifacts are valid only on public attempt nodes; private and unlisted submissions do not count in campaign snapshots or dispatch submission hook runs.
 - Workflow step types include `flywheel/http_request@v1`, `flywheel/http_poll@v1`, `flywheel/json_extract@v1`, `flywheel/load_artifact@v1`, `flywheel/upsert_artifact@v1`, and `flywheel/add_node_tags@v1`.
 - `flywheel/upsert_artifact@v1` selectors are authored under `with.match`; `match.metadata` is subset matching and ambiguous selectors fail terminally.
 - `flywheel/add_node_tags@v1` adds ordinary root graph tags to a target node and preserves existing tag assignments; one-only tags are rejected in v1.

package/src/cli.mjs

@@ -15,6 +15,7 @@ import {
   isSkillOnlyHost,
   normalizeHosts,
 } from "./agents.mjs";
+import { generateCompletionScript } from "./completion.mjs";
 import {
   readEntryServerUrl,
   readNamedConfigEntry,
@@ -45,6 +46,7 @@ import {
   buildGuidedSkillInstallPrompt,
   runMcpModeCommand,
 } from "./setup/modes/mcp-command.mjs";
+import { COMPLETION_SHELL_CHOICES } from "./public-command-metadata.mjs";
 import { findFlywheelMcpEntryNames } from "./setup/shared/prior-mode-detect.mjs";
 import { renderSetupSummary } from "./setup/shared/summary.mjs";
 
@@ -475,6 +477,20 @@ async function runSetupCommandViaRouter(options) {
   });
 }
 
+async function runCompletionCommand(shell, options) {
+  try {
+    const script = await generateCompletionScript({
+      shell,
+      includeBashCompletionLib: options.includeBashCompletionLib === true,
+    });
+    process.stdout.write(script);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  }
+}
+
 function parseUninstallScope(value) {
   const normalized = String(value || "")
     .trim()
@@ -1146,6 +1162,45 @@ Examples:
 `,
     );
 
+  program
+    .command("completion <shell>")
+    .description("Generate a shell completion script")
+    .addHelpText(
+      "before",
+      `${pc.bold(pc.cyan("✻ Flywheel Completion"))}
+
+Generate shell completion scripts from the public Flywheel Usage spec.
+Supported shells: ${COMPLETION_SHELL_CHOICES.join(", ")}.
+Requires the official Usage CLI executable on PATH.
+`,
+    )
+    .option(
+      "--include-bash-completion-lib",
+      "Include Usage's bash completion library in bash output",
+    )
+    .addHelpText(
+      "after",
+      `
+Usage CLI prerequisite:
+  ${pc.green("mise use -g usage")}
+  ${pc.green("brew install usage")}
+  ${pc.green("cargo install usage-cli")}
+  ${pc.green("cargo binstall usage-cli")}
+  ${pc.green("pacman -S usage")}
+
+Examples:
+  ${pc.green("flywheel completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/flywheel")}
+  ${pc.green("flywheel completion zsh > ~/.zsh/completions/_flywheel")}
+  ${pc.green("flywheel completion fish > ~/.config/fish/completions/flywheel.fish")}
+  ${pc.green("flywheel completion powershell > flywheel.ps1")}
+  ${pc.green("flywheel completion nu > ~/.config/nushell/autoload/flywheel.nu")}
+  ${pc.green("flywheel completion nushell > ~/.config/nushell/autoload/flywheel.nu")}
+`,
+    )
+    .action(async (shell, options) => {
+      await runCompletionCommand(shell, options);
+    });
+
   program
     .command("setup")
     .description("Set up Flywheel for your AI coding host")

package/src/completion.mjs

@@ -0,0 +1,326 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+
+import {
+  loadPackageVersion,
+  usageExtrasArg,
+  usageVersionArg,
+} from "./public-command-metadata.mjs";
+import { runRuntimeCli } from "./runtime/delegate.mjs";
+
+export const SUPPORTED_COMPLETION_SHELLS = [
+  "bash",
+  "zsh",
+  "fish",
+  "powershell",
+  "nu",
+  "nushell",
+];
+
+const DEFAULT_WINDOWS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+const SUPPORTED_COMPLETION_SHELLS_FOR_ERRORS = [
+  "bash",
+  "fish",
+  "nu",
+  "nushell",
+  "powershell",
+  "zsh",
+];
+
+const USAGE_INSTALL_HINTS = [
+  "mise use -g usage",
+  "brew install usage",
+  "cargo install usage-cli",
+  "cargo binstall usage-cli",
+  "pacman -S usage",
+];
+
+const DEFAULT_USAGE_BIN = "usage";
+const MAX_COMPLETION_BUFFER_BYTES = 50 * 1024 * 1024;
+
+function supportedShellList() {
+  return SUPPORTED_COMPLETION_SHELLS_FOR_ERRORS.join(", ");
+}
+
+function missingUsageMessage(name) {
+  return [
+    `official Usage CLI not found or not executable: ${name}`,
+    "Install usage with one of:",
+    ...USAGE_INSTALL_HINTS.map((hint) => `  ${hint}`),
+  ].join("\n");
+}
+
+function isExecutable(filePath) {
+  try {
+    accessSync(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hasPathSeparator(value) {
+  return (
+    value.includes(path.sep) ||
+    value.includes(path.posix.sep) ||
+    value.includes(path.win32.sep)
+  );
+}
+
+function pathextCandidates(env, platform) {
+  const useWindowsDefaultPathext =
+    platform === "win32" && String(env.PATHEXT ?? "").trim() === "";
+  const rawPathext =
+    useWindowsDefaultPathext
+      ? DEFAULT_WINDOWS_PATHEXT
+      : String(env.PATHEXT ?? "");
+  const candidates = [];
+  const seen = new Set();
+  for (const rawExtension of rawPathext.split(";")) {
+    const trimmed = rawExtension.trim();
+    if (!trimmed) continue;
+    const extension = trimmed.startsWith(".") ? trimmed : `.${trimmed}`;
+    const variants = useWindowsDefaultPathext
+      ? [extension.toLowerCase(), extension, extension.toUpperCase()]
+      : [extension, extension.toLowerCase(), extension.toUpperCase()];
+    for (const candidate of variants) {
+      if (!seen.has(candidate)) {
+        candidates.push(candidate);
+        seen.add(candidate);
+      }
+    }
+  }
+  return candidates;
+}
+
+function executableNameCandidates(name, env, platform = process.platform) {
+  const candidates = [name];
+  const lowerName = name.toLowerCase();
+  const seen = new Set(candidates);
+  for (const extension of pathextCandidates(env, platform)) {
+    if (lowerName.endsWith(extension.toLowerCase())) continue;
+    const candidate = `${name}${extension}`;
+    if (!seen.has(candidate)) {
+      candidates.push(candidate);
+      seen.add(candidate);
+    }
+  }
+  return candidates;
+}
+
+export function sanitizeUsageEnv(env = process.env) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key.toUpperCase().startsWith("FLYWHEEL_")) continue;
+    if (value !== undefined) {
+      sanitized[key] = value;
+    }
+  }
+  return sanitized;
+}
+
+function isWindowsCommandShim(filePath, platform) {
+  return (
+    platform === "win32" &&
+    [".bat", ".cmd"].includes(path.extname(filePath).toLowerCase())
+  );
+}
+
+function quoteWindowsCommandPath(filePath) {
+  return `"${String(filePath).replaceAll('"', '""')}"`;
+}
+
+function resolveWindowsCommandShell(env) {
+  return env.ComSpec || env.COMSPEC || "cmd.exe";
+}
+
+function buildUsageInvocation({ usagePath, args, env, platform }) {
+  if (!isWindowsCommandShim(usagePath, platform)) {
+    return { command: usagePath, args };
+  }
+  const commandLine = `"${[quoteWindowsCommandPath(usagePath), ...args].join(" ")}"`;
+  return {
+    command: resolveWindowsCommandShell(env),
+    args: ["/d", "/s", "/c", commandLine],
+  };
+}
+
+export function normalizeCompletionShell(value) {
+  if (value === "nushell") {
+    return "nu";
+  }
+  if (SUPPORTED_COMPLETION_SHELLS.includes(value)) {
+    return value;
+  }
+  throw new Error(
+    `unsupported completion shell "${value}". Supported shells: ${supportedShellList()}`,
+  );
+}
+
+export function buildUsageCompletionArgs({
+  shell,
+  includeBashCompletionLib = false,
+}) {
+  const normalizedShell = normalizeCompletionShell(shell);
+  if (includeBashCompletionLib && normalizedShell !== "bash") {
+    throw new Error("--include-bash-completion-lib is only supported for bash");
+  }
+  const args = ["generate", "completion", normalizedShell, "flywheel", "-f", "-"];
+  if (includeBashCompletionLib) {
+    args.push("--include-bash-completion-lib");
+  }
+  return args;
+}
+
+export function findExecutable(
+  name,
+  env = process.env,
+  platform = process.platform,
+) {
+  if (!name) {
+    return null;
+  }
+  if (path.isAbsolute(name) || hasPathSeparator(name)) {
+    return isExecutable(name) ? name : null;
+  }
+  const delimiter = platform === "win32" ? ";" : path.delimiter;
+  for (const entry of String(env.PATH ?? "").split(delimiter)) {
+    if (!entry) continue;
+    for (const candidateName of executableNameCandidates(name, env, platform)) {
+      const candidate = path.join(entry, candidateName);
+      if (isExecutable(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+async function capturePublicUsageSpec() {
+  let stdout = "";
+  let stderr = "";
+  const version = await loadPackageVersion();
+  const exitCode = await runRuntimeCli([
+    "--usage",
+    usageExtrasArg(),
+    usageVersionArg(version),
+  ], {
+    stdout: (chunk) => {
+      stdout += chunk instanceof Uint8Array ? Buffer.from(chunk).toString("utf8") : chunk;
+    },
+    stderr: (chunk) => {
+      stderr += chunk instanceof Uint8Array ? Buffer.from(chunk).toString("utf8") : chunk;
+    },
+  });
+  if (exitCode !== 0) {
+    const detail = stderr.trim() ? `: ${stderr.trim()}` : "";
+    throw new Error(`failed to capture Flywheel Usage spec${detail}`);
+  }
+  return stdout;
+}
+
+function runUsageCompletion({ command, args, usageSpec, env }) {
+  return awaitChildProcess({
+    child: spawn(command, args, {
+      env: sanitizeUsageEnv(env),
+      stdio: ["pipe", "pipe", "pipe"],
+    }),
+    input: usageSpec,
+  });
+}
+
+function awaitChildProcess({ child, input }) {
+  return new Promise((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let stdinError = null;
+
+    function settle(callback, value) {
+      if (settled) return;
+      settled = true;
+      callback(value);
+    }
+
+    function append(streamName, chunk) {
+      if (streamName === "stdout") {
+        stdout += chunk.toString("utf8");
+        if (Buffer.byteLength(stdout, "utf8") > MAX_COMPLETION_BUFFER_BYTES) {
+          child.kill();
+          settle(reject, new Error("usage completion stdout exceeded 50 MiB"));
+        }
+      } else {
+        stderr += chunk.toString("utf8");
+        if (Buffer.byteLength(stderr, "utf8") > MAX_COMPLETION_BUFFER_BYTES) {
+          child.kill();
+          settle(reject, new Error("usage completion stderr exceeded 50 MiB"));
+        }
+      }
+    }
+
+    child.stdout.on("data", (chunk) => append("stdout", chunk));
+    child.stderr.on("data", (chunk) => append("stderr", chunk));
+    child.stdin.on("error", (error) => {
+      if (error.code === "EPIPE") {
+        stdinError = error;
+        return;
+      }
+      child.kill();
+      settle(reject, error);
+    });
+    child.on("error", (error) => settle(reject, error));
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      if (code === 0) {
+        if (stdinError) {
+          settle(
+            reject,
+            new Error(
+              `usage stdin closed before Flywheel Usage spec was written: ${stdinError.message}`,
+            ),
+          );
+          return;
+        }
+        settle(resolve, stdout);
+        return;
+      }
+      const detail = stderr.trim() ? `\n${stderr.trim()}` : "";
+      const status = signal ? `signal ${signal}` : `exit code ${code}`;
+      settle(reject, new Error(`usage generate completion failed with ${status}.${detail}`));
+    });
+    child.stdin.end(input);
+  });
+}
+
+export async function generateCompletionScript({
+  shell,
+  includeBashCompletionLib = false,
+  usageBin,
+  env = process.env,
+  platform = process.platform,
+  usageSpec,
+  captureUsageSpec = capturePublicUsageSpec,
+} = {}) {
+  const args = buildUsageCompletionArgs({ shell, includeBashCompletionLib });
+  const usageName = usageBin ?? env.USAGE_BIN ?? DEFAULT_USAGE_BIN;
+  const usagePath = findExecutable(usageName, env, platform);
+  if (!usagePath) {
+    throw new Error(missingUsageMessage(usageName));
+  }
+
+  const spec = usageSpec ?? (await captureUsageSpec());
+  const usageInvocation = buildUsageInvocation({
+    usagePath,
+    args,
+    env,
+    platform,
+  });
+  return await runUsageCompletion({
+    command: usageInvocation.command,
+    args: usageInvocation.args,
+    usageSpec: spec,
+    env,
+  });
+}

package/src/public-command-metadata.mjs

@@ -0,0 +1,240 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_JSON_PATH = path.resolve(__dirname, "..", "package.json");
+
+export const COMPLETION_SHELL_CHOICES = [
+  "bash",
+  "zsh",
+  "fish",
+  "powershell",
+  "nu",
+  "nushell",
+];
+
+export const HELP_EXTRAS = [
+  {
+    group: "setup-admin",
+    name: "completion",
+    summary: "Generate shell completion scripts.",
+  },
+  {
+    group: "setup-admin",
+    name: "setup",
+    summary: "Install Flywheel CLI + MCP + skills.",
+  },
+  {
+    group: "setup-admin",
+    name: "uninstall",
+    summary: "Uninstall Flywheel artifacts.",
+  },
+];
+
+export const USAGE_EXTRAS = [
+  {
+    group: "setup-admin",
+    name: "completion",
+    summary: "Generate a shell completion script from the public Flywheel Usage spec",
+    endpoints: [],
+    args: [
+      {
+        name: "shell",
+        type: "string",
+        description: "Shell to generate completions for",
+        choices: COMPLETION_SHELL_CHOICES,
+      },
+    ],
+    required: [],
+    optional: [
+      {
+        name: "include-bash-completion-lib",
+        type: "boolean",
+        description: "Include Usage's bash completion library in bash output",
+      },
+    ],
+    examples: [
+      {
+        description: "Generate bash completions",
+        invocation: "flywheel completion bash",
+      },
+      {
+        description: "Generate zsh completions",
+        invocation: "flywheel completion zsh",
+      },
+      {
+        description: "Generate Nushell completions with the alias",
+        invocation: "flywheel completion nushell",
+      },
+    ],
+    related: ["setup", "uninstall"],
+  },
+  {
+    group: "setup-admin",
+    name: "setup",
+    summary: "Set up Flywheel for your AI coding host",
+    endpoints: [],
+    required: [],
+    optional: [
+      { name: "claude", type: "boolean", description: "Set up for Claude Code" },
+      { name: "cursor", type: "boolean", description: "Set up for Cursor" },
+      { name: "universal", type: "boolean", description: "Set up for Universal (.agents/skills)" },
+      { name: "antigravity", type: "boolean", description: "Set up for Antigravity (.agent/skills)" },
+      { name: "opencode", type: "boolean", description: "Set up for OpenCode" },
+      { name: "codex", type: "boolean", description: "Set up for Codex" },
+      { name: "gemini", type: "boolean", description: "Set up for Gemini CLI" },
+      { name: "pi-mono", type: "boolean", description: "Set up for Pi (pi-mono)" },
+      { name: "hermes-agent", type: "boolean", description: "Set up for Hermes Agent" },
+      { name: "openclaw", type: "boolean", description: "Set up for OpenClaw" },
+      {
+        name: "mode",
+        type: "string",
+        usage: "--mode <MODE>",
+        description: "Install mode: mcp | cli",
+        choices: ["mcp", "cli"],
+      },
+      { name: "mcp", type: "boolean", description: "Alias for --mode mcp" },
+      { name: "cli", type: "boolean", description: "Alias for --mode cli" },
+      {
+        name: "project",
+        type: "boolean",
+        usage: "-p --project",
+        description: "Configure for current project instead of globally",
+      },
+      {
+        name: "yes",
+        type: "boolean",
+        usage: "-y --yes",
+        description: "Skip confirmation prompts",
+      },
+      {
+        name: "api-key",
+        type: "string",
+        usage: "--api-key <KEY>",
+        description: "Use API key authentication",
+      },
+      { name: "oauth", type: "boolean", description: "Use OAuth endpoint (IDE handles auth flow)" },
+      { name: "install-skill", type: "boolean", description: "Install or refresh the bundled Flywheel skills" },
+      { name: "skip-skill", type: "boolean", description: "Skip bundled skill installation (MCP-only setup)" },
+      {
+        name: "auth-mode",
+        type: "string",
+        usage: "--auth-mode <MODE>",
+        description: "API-key mint flow: auto | loopback | device",
+        default: "auto",
+        choices: ["auto", "loopback", "device"],
+      },
+      {
+        name: "base-url",
+        type: "string",
+        usage: "--base-url <URL>",
+        description: "Public Flywheel origin used for setup and MCP config",
+      },
+      { name: "name", type: "string", usage: "--name <NAME>", description: "MCP server name" },
+      { name: "force", type: "boolean", description: "Reconcile prior install mode automatically via uninstall" },
+    ],
+    examples: [
+      {
+        description: "Install MCP wiring and bundled skills",
+        invocation: "npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill",
+      },
+      {
+        description: "Configure Codex MCP wiring without bundled skills",
+        invocation: "npx --yes @paradigma-inc/flywheel setup --mode mcp --skip-skill --codex --project",
+      },
+      {
+        description: "Install CLI-mode bundled skills for Codex",
+        invocation: "npx --yes @paradigma-inc/flywheel setup --mode cli --codex --project",
+      },
+    ],
+    related: ["uninstall"],
+  },
+  {
+    group: "setup-admin",
+    name: "uninstall",
+    summary: "Remove Flywheel MCP entries and bundled skills from selected hosts",
+    endpoints: [],
+    required: [],
+    optional: [
+      { name: "claude", type: "boolean", description: "Uninstall for Claude Code" },
+      { name: "cursor", type: "boolean", description: "Uninstall for Cursor" },
+      { name: "universal", type: "boolean", description: "Uninstall bundled skills from .agents/skills" },
+      { name: "antigravity", type: "boolean", description: "Uninstall bundled skills from .agent/skills" },
+      { name: "opencode", type: "boolean", description: "Uninstall for OpenCode" },
+      { name: "codex", type: "boolean", description: "Uninstall for Codex" },
+      { name: "gemini", type: "boolean", description: "Uninstall for Gemini CLI" },
+      { name: "pi-mono", type: "boolean", description: "Uninstall for Pi (pi-mono)" },
+      { name: "hermes-agent", type: "boolean", description: "Uninstall for Hermes Agent" },
+      { name: "openclaw", type: "boolean", description: "Uninstall for OpenClaw" },
+      {
+        name: "hosts",
+        type: "string",
+        usage: "--hosts <LIST>",
+        description: "Comma-separated host list",
+      },
+      {
+        name: "scope",
+        type: "string",
+        usage: "--scope <SCOPE>",
+        description: "all | global | project",
+        choices: ["all", "global", "project"],
+      },
+      {
+        name: "name",
+        type: "string",
+        usage: "--name <NAME>",
+        description: "MCP server name to remove",
+      },
+      {
+        name: "yes",
+        type: "boolean",
+        usage: "-y --yes",
+        description: "Skip uninstall selection prompts",
+      },
+    ],
+    examples: [
+      {
+        description: "Uninstall Codex project-scope artifacts",
+        invocation: "npx --yes @paradigma-inc/flywheel uninstall --codex --scope project",
+      },
+      {
+        description: "Uninstall selected hosts across all scopes",
+        invocation: "npx --yes @paradigma-inc/flywheel uninstall --hosts claude,codex --scope all --yes",
+      },
+    ],
+    related: ["setup"],
+  },
+];
+
+export function helpExtrasArg() {
+  return `--_help_extras=${JSON.stringify(HELP_EXTRAS)}`;
+}
+
+export function usageExtrasArg() {
+  return `--_usage_extras=${JSON.stringify(USAGE_EXTRAS)}`;
+}
+
+export function usageVersionArg(version) {
+  return `--_usage_version=${version}`;
+}
+
+let cachedPackageVersion = null;
+
+export async function loadPackageVersion() {
+  if (cachedPackageVersion !== null) {
+    return cachedPackageVersion;
+  }
+  try {
+    const raw = await readFile(PACKAGE_JSON_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version === "string" && parsed.version.trim()) {
+      cachedPackageVersion = parsed.version.trim();
+      return cachedPackageVersion;
+    }
+  } catch {
+    // Fall through to deterministic fallback.
+  }
+  cachedPackageVersion = "0.0.0";
+  return cachedPackageVersion;
+}