nofax 0.2.0

package/src/adapters/gemini.mjs

@@ -0,0 +1,57 @@
+import { buildAgentSummary } from '../protocol.mjs';
+import { requestApproval, sendNotification } from '../ntfy.mjs';
+
+export async function handleGeminiNotification(input, {
+  config,
+  sendNotificationImpl = sendNotification
+} = {}) {
+  if (!input || input.hook_event_name !== 'Notification') throw new Error('NOFAX_GEMINI_EVENT');
+  const type = typeof input.notification_type === 'string' && input.notification_type
+    ? input.notification_type
+    : 'Notification';
+  await sendNotificationImpl({
+    config,
+    title: `Gemini CLI: ${type}`,
+    message: buildAgentSummary({
+      source: 'Gemini CLI',
+      message: typeof input.message === 'string' ? input.message : 'Gemini CLI needs attention.',
+      toolInput: input.details
+    })
+  });
+  return {};
+}
+
+export async function handleGeminiHook(input, {
+  config,
+  requestApprovalImpl = requestApproval,
+  sendNotificationImpl = sendNotification,
+  onError = () => {}
+} = {}) {
+  if (!input || typeof input.hook_event_name !== 'string') throw new Error('NOFAX_GEMINI_EVENT');
+  if (input.hook_event_name === 'Notification') {
+    return handleGeminiNotification(input, { config, sendNotificationImpl });
+  }
+  if (input.hook_event_name !== 'BeforeTool') throw new Error('NOFAX_GEMINI_EVENT');
+  if (typeof input.tool_name !== 'string' || !input.tool_name) throw new Error('NOFAX_GEMINI_TOOL');
+
+  try {
+    const result = await requestApprovalImpl({
+      config,
+      title: `Gemini CLI needs approval: ${input.tool_name}`,
+      message: buildAgentSummary({
+        source: 'Gemini CLI',
+        toolName: input.tool_name,
+        cwd: input.cwd,
+        toolInput: input.tool_input
+      })
+    });
+    if (result.decision === 'allow') return { decision: 'allow' };
+    if (result.decision === 'deny') {
+      return { decision: 'deny', reason: 'Denied remotely via Nofax.' };
+    }
+    return {};
+  } catch (error) {
+    onError(error);
+    return {};
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,191 @@
+import { initConfig, loadConfig } from './config.mjs';
+import { requestApproval, requestRefinement, sendNotification } from './ntfy.mjs';
+import { handleClaudePermissionRequest } from './adapters/claude.mjs';
+import { handleCodexPermissionRequest } from './adapters/codex.mjs';
+import { handleGeminiHook } from './adapters/gemini.mjs';
+
+const HELP = `nofax - remote approvals and notifications for coding agents\n\nUsage:\n  nofax init [--server URL] [--topic TOPIC] [--timeout SECONDS] [--force]\n  nofax test\n  nofax notify [--title TITLE] MESSAGE...\n  nofax approve [--title TITLE] MESSAGE...\n  nofax refine [--title TITLE] MESSAGE...\n  nofax mcp\n  nofax config\n  nofax hook claude\n  nofax hook codex\n  nofax hook gemini\n\nEnvironment:\n  NOFAX_HOME   Override ~/.nofax\n`;
+
+function parseArgs(args) {
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === '--force') {
+      flags.force = true;
+      continue;
+    }
+    if (['--title', '--server', '--topic', '--timeout'].includes(value)) {
+      const next = args[index + 1];
+      if (next === undefined) throw new Error(`NOFAX_FLAG_VALUE:${value}`);
+      flags[value.slice(2)] = next;
+      index += 1;
+      continue;
+    }
+    if (value.startsWith('--')) throw new Error(`NOFAX_UNKNOWN_FLAG:${value}`);
+    positionals.push(value);
+  }
+  return { flags, positionals };
+}
+
+async function readStdin(stdinText) {
+  if (stdinText !== undefined) return stdinText;
+  let text = '';
+  for await (const chunk of process.stdin) text += chunk;
+  return text;
+}
+
+function writeJson(stream, value) {
+  stream.write(`${JSON.stringify(value)}\n`);
+}
+
+async function runHook(adapter, deps) {
+  const inputText = await readStdin(deps.stdinText);
+  let input;
+  try {
+    input = JSON.parse(inputText);
+  } catch {
+    throw new Error('NOFAX_HOOK_INVALID_JSON');
+  }
+  const config = await deps.loadConfigImpl({ env: deps.env });
+  const onError = (error) => deps.stderr.write(`nofax: ${error.message}\n`);
+  let output;
+  if (adapter === 'claude') {
+    output = await handleClaudePermissionRequest(input, { config, requestApprovalImpl: deps.requestApprovalImpl, onError });
+  } else if (adapter === 'codex') {
+    output = await handleCodexPermissionRequest(input, { config, requestApprovalImpl: deps.requestApprovalImpl, onError });
+  } else if (adapter === 'gemini') {
+    output = await handleGeminiHook(input, {
+      config,
+      requestApprovalImpl: deps.requestApprovalImpl,
+      sendNotificationImpl: deps.sendNotificationImpl,
+      onError
+    });
+  } else {
+    throw new Error(`NOFAX_HOOK_UNSUPPORTED:${adapter}`);
+  }
+
+  if (output === null) {
+    deps.stderr.write('nofax: no remote decision; continuing with native approval.\n');
+    return 0;
+  }
+  writeJson(deps.stdout, output);
+  return 0;
+}
+
+export async function runCli(args, overrides = {}) {
+  const deps = {
+    env: overrides.env ?? process.env,
+    stdinText: overrides.stdinText,
+    stdout: overrides.stdout ?? process.stdout,
+    stderr: overrides.stderr ?? process.stderr,
+    initConfigImpl: overrides.initConfigImpl ?? initConfig,
+    loadConfigImpl: overrides.loadConfigImpl ?? loadConfig,
+    requestApprovalImpl: overrides.requestApprovalImpl ?? requestApproval,
+    requestRefinementImpl: overrides.requestRefinementImpl ?? requestRefinement,
+    sendNotificationImpl: overrides.sendNotificationImpl ?? sendNotification,
+    runMcpServerImpl: overrides.runMcpServerImpl ?? (async () => {
+      const { runMcpServer } = await import('./mcp-server.mjs');
+      await runMcpServer();
+    })
+  };
+
+  try {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+      deps.stdout.write(HELP);
+      return 0;
+    }
+
+    const command = args[0];
+    if (command === 'init') {
+      const { flags } = parseArgs(args.slice(1));
+      const timeoutSeconds = flags.timeout === undefined ? undefined : Number(flags.timeout);
+      const config = await deps.initConfigImpl({
+        env: deps.env,
+        ...(flags.server === undefined ? {} : { server: flags.server }),
+        ...(flags.topic === undefined ? {} : { topic: flags.topic }),
+        ...(timeoutSeconds === undefined ? {} : { timeoutSeconds }),
+        force: flags.force === true
+      });
+      deps.stdout.write('Nofax ready.\n');
+      deps.stdout.write(`Subscribe your ntfy app to: ${config.server}/${config.topic}\n`);
+      deps.stdout.write('Then run: nofax test\n');
+      return 0;
+    }
+
+    if (command === 'config') {
+      const config = await deps.loadConfigImpl({ env: deps.env });
+      deps.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+      return 0;
+    }
+
+    if (command === 'test') {
+      const config = await deps.loadConfigImpl({ env: deps.env });
+      await deps.sendNotificationImpl({
+        config,
+        title: 'Nofax is connected',
+        message: 'If you can read this on your phone, Nofax is ready.'
+      });
+      deps.stdout.write('Test notification sent.\n');
+      return 0;
+    }
+
+    if (command === 'notify') {
+      const { flags, positionals } = parseArgs(args.slice(1));
+      if (positionals.length === 0) throw new Error('NOFAX_MESSAGE_REQUIRED');
+      const config = await deps.loadConfigImpl({ env: deps.env });
+      await deps.sendNotificationImpl({
+        config,
+        title: flags.title ?? 'Nofax',
+        message: positionals.join(' ')
+      });
+      deps.stdout.write('Notification sent.\n');
+      return 0;
+    }
+
+    if (command === 'approve') {
+      const { flags, positionals } = parseArgs(args.slice(1));
+      if (positionals.length === 0) throw new Error('NOFAX_MESSAGE_REQUIRED');
+      const config = await deps.loadConfigImpl({ env: deps.env });
+      const result = await deps.requestApprovalImpl({
+        config,
+        title: flags.title ?? 'Nofax approval',
+        message: positionals.join(' ')
+      });
+      writeJson(deps.stdout, { decision: result.decision });
+      return result.decision === 'timeout' ? 3 : 0;
+    }
+
+    if (command === 'refine') {
+      const { flags, positionals } = parseArgs(args.slice(1));
+      if (positionals.length === 0) throw new Error('NOFAX_MESSAGE_REQUIRED');
+      const config = await deps.loadConfigImpl({ env: deps.env });
+      const result = await deps.requestRefinementImpl({
+        config,
+        title: flags.title ?? 'Nofax refinement',
+        message: positionals.join(' ')
+      });
+      writeJson(deps.stdout, {
+        decision: result.decision,
+        ...(result.text === undefined ? {} : { text: result.text })
+      });
+      return result.decision === 'timeout' ? 3 : 0;
+    }
+
+    if (command === 'mcp') {
+      await deps.runMcpServerImpl();
+      return 0;
+    }
+
+    if (command === 'hook') {
+      const adapter = args[1];
+      if (!adapter) throw new Error('NOFAX_HOOK_REQUIRED');
+      return runHook(adapter, deps);
+    }
+
+    throw new Error(`NOFAX_UNKNOWN_COMMAND:${command}`);
+  } catch (error) {
+    deps.stderr.write(`nofax: ${error.message}\n`);
+    return 1;
+  }
+}

package/src/config.mjs

@@ -0,0 +1,91 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { createPhoneTopic } from './protocol.mjs';
+
+export const DEFAULT_SERVER = 'https://ntfy.sh';
+export const DEFAULT_TIMEOUT_SECONDS = 300;
+
+export function resolveNofaxHome({ home, env = process.env } = {}) {
+  const configured = home ?? env.NOFAX_HOME;
+  if (configured !== undefined) {
+    const trimmed = String(configured).trim();
+    if (!trimmed) throw new Error('NOFAX_HOME_EMPTY');
+    return isAbsolute(trimmed) ? resolve(trimmed) : resolve(process.cwd(), trimmed);
+  }
+  return join(homedir(), '.nofax');
+}
+
+export function normalizeServer(input) {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new Error('NOFAX_SERVER_INVALID');
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new Error('NOFAX_SERVER_PROTOCOL');
+  if (url.username || url.password) throw new Error('NOFAX_SERVER_CREDENTIALS');
+  if ((url.pathname && url.pathname !== '/') || url.search || url.hash) throw new Error('NOFAX_SERVER_PATH');
+  return `${url.protocol}//${url.host}`;
+}
+
+function validateTopic(topic) {
+  if (typeof topic !== 'string' || topic.length < 24 || topic.length > 128 || !/^[A-Za-z0-9_-]+$/.test(topic)) {
+    throw new Error('NOFAX_TOPIC_INVALID');
+  }
+  return topic;
+}
+
+function validateTimeout(value) {
+  if (!Number.isInteger(value) || value < 5 || value > 3600) throw new Error('NOFAX_TIMEOUT_INVALID');
+  return value;
+}
+
+export function validateConfig(input) {
+  if (!input || input.version !== 1) throw new Error('NOFAX_CONFIG_VERSION');
+  return {
+    version: 1,
+    server: normalizeServer(input.server),
+    topic: validateTopic(input.topic),
+    timeoutSeconds: validateTimeout(input.timeoutSeconds)
+  };
+}
+
+export async function loadConfig({ home, env } = {}) {
+  const root = resolveNofaxHome({ home, env });
+  try {
+    const parsed = JSON.parse(await readFile(join(root, 'config.json'), 'utf8'));
+    return validateConfig(parsed);
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new Error('NOFAX_NOT_INITIALIZED');
+    if (error instanceof SyntaxError) throw new Error('NOFAX_CONFIG_INVALID_JSON');
+    throw error;
+  }
+}
+
+export async function initConfig({ home, env, server = DEFAULT_SERVER, topic, timeoutSeconds = DEFAULT_TIMEOUT_SECONDS, force = false } = {}) {
+  const root = resolveNofaxHome({ home, env });
+  if (!force) {
+    try {
+      return await loadConfig({ home: root });
+    } catch (error) {
+      if (error.message !== 'NOFAX_NOT_INITIALIZED') throw error;
+    }
+  }
+
+  const config = validateConfig({
+    version: 1,
+    server,
+    topic: topic ?? createPhoneTopic(),
+    timeoutSeconds
+  });
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const path = join(root, 'config.json');
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  try {
+    await chmod(path, 0o600);
+  } catch {
+    // Windows may not honor POSIX mode bits; the file still lives in the user's profile.
+  }
+  return config;
+}

package/src/index.mjs

@@ -0,0 +1,8 @@
+export * from './config.mjs';
+export * from './protocol.mjs';
+export * from './ntfy.mjs';
+export * from './requests.mjs';
+export * from './mcp-tools.mjs';
+export * from './adapters/claude.mjs';
+export * from './adapters/codex.mjs';
+export * from './adapters/gemini.mjs';

package/src/mcp-server.mjs

@@ -0,0 +1,141 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
+import { createMcpToolHandlers } from './mcp-tools.mjs';
+
+export const MCP_TOOL_NAMES = Object.freeze([
+  'nofax_notify',
+  'nofax_request_approval',
+  'nofax_request_choice',
+  'nofax_request_refinement',
+  'nofax_wait_for_response',
+  'nofax_get_request',
+  'nofax_list_pending'
+]);
+
+const SERVER_INSTRUCTIONS = [
+  'Nofax is a human-attention and approval bridge.',
+  'One-way nofax_notify calls do not require waiting.',
+  'Every nofax_request_* call returns a durable pending requestId.',
+  'For any pending request, you MUST call nofax_wait_for_response with that requestId and repeat whenever it returns pending.',
+  'Do not infer approval, continue a guarded action, claim completion, or substitute your own decision while a Nofax request is pending.',
+  'Only a terminal human response authorizes the next step, and only within the authority the caller already had.',
+  'If the terminal response is refine, apply the supplied refinement and request a new approval if the resulting action still requires approval.'
+].join(' ');
+
+function result(value) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value) }],
+    structuredContent: value
+  };
+}
+
+export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
+  const server = new McpServer(
+    { name: 'nofax', version: '0.2.0' },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
+
+  server.registerTool(
+    'nofax_notify',
+    {
+      title: 'Send Nofax notification',
+      description: 'Send a one-way phone notification. This tool is informational and does not create a human-response wait.',
+      inputSchema: z.object({
+        title: z.string().min(1).max(120).optional(),
+        message: z.string().min(1).max(2200)
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    async (args) => result(await handlers.notify(args))
+  );
+
+  server.registerTool(
+    'nofax_request_approval',
+    {
+      title: 'Request human approval',
+      description: 'Send Allow/Deny to the phone and return a durable pending requestId. IMPORTANT: after this tool returns pending, call nofax_wait_for_response and repeat while it remains pending. Never continue the guarded action without a terminal Allow response. Set allowRefine when the human should also be able to send refinement text.',
+      inputSchema: z.object({
+        title: z.string().min(1).max(120).optional(),
+        message: z.string().min(1).max(2200),
+        allowRefine: z.boolean().optional()
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    async (args) => result(await handlers.requestApproval(args))
+  );
+
+  server.registerTool(
+    'nofax_request_choice',
+    {
+      title: 'Request human choice',
+      description: 'Send up to three explicit options to the phone and return a durable pending requestId. IMPORTANT: call nofax_wait_for_response and repeat while pending; do not choose on the human\'s behalf.',
+      inputSchema: z.object({
+        title: z.string().min(1).max(120).optional(),
+        message: z.string().min(1).max(2200),
+        options: z.array(z.union([
+          z.string().min(1).max(80),
+          z.object({ value: z.string().min(1).max(80), label: z.string().min(1).max(32) })
+        ])).min(1).max(3)
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    async (args) => result(await handlers.requestChoice(args))
+  );
+
+  server.registerTool(
+    'nofax_request_refinement',
+    {
+      title: 'Request human refinement',
+      description: 'Ask the human for free-text refinement through the configured Nofax Refine iOS Shortcut. Returns a durable pending requestId. IMPORTANT: call nofax_wait_for_response and repeat while pending.',
+      inputSchema: z.object({
+        title: z.string().min(1).max(120).optional(),
+        message: z.string().min(1).max(2200)
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    async (args) => result(await handlers.requestRefinement(args))
+  );
+
+  server.registerTool(
+    'nofax_wait_for_response',
+    {
+      title: 'Wait for Nofax human response',
+      description: 'Long-poll a durable Nofax request for up to 240 seconds. If the result is pending, you MUST call this tool again with the same requestId. Repeat indefinitely until a terminal response is returned or the user explicitly changes/cancels the goal. Do not continue the guarded action while pending.',
+      inputSchema: z.object({
+        requestId: z.string().min(24).max(84),
+        waitSeconds: z.number().int().min(1).max(240).optional()
+      }),
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => result(await handlers.waitForResponse(args))
+  );
+
+  server.registerTool(
+    'nofax_get_request',
+    {
+      title: 'Get Nofax request',
+      description: 'Recover safe metadata and terminal state for a durable Nofax request. Secret response topics are never returned.',
+      inputSchema: z.object({ requestId: z.string().min(24).max(84) }),
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    async (args) => result(await handlers.getRequest(args))
+  );
+
+  server.registerTool(
+    'nofax_list_pending',
+    {
+      title: 'List pending Nofax requests',
+      description: 'List a bounded set of unresolved Nofax request handles for recovery after client or conversation interruption. Secret response topics are never returned.',
+      inputSchema: z.object({ limit: z.number().int().min(1).max(100).optional() }),
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    async (args) => result(await handlers.listPending(args))
+  );
+
+  return server;
+}
+
+export async function runMcpServer() {
+  await serveStdio(() => buildMcpServer());
+}