octiqflow 0.1.52

package/README.md

@@ -0,0 +1,39 @@
+# OctiqFlow
+
+OctiqFlow is an agent workflow orchestrator: real terminals, Claude Code,
+Codex, and pi.dev in one browser control plane.
+
+## Run now
+
+```bash
+npx octiqflow
+```
+
+This starts OctiqFlow in the foreground and prints the local URL. Node.js 18+
+is the only build/runtime prerequisite; the matching native server and browser
+client are installed automatically for macOS arm64/x64, Linux x64, or Windows
+x64.
+
+## Install on macOS
+
+```bash
+npm install -g octiqflow
+octiqflow install
+```
+
+The second command installs and starts a launchd user service, then opens the
+authenticated local URL. It keeps running after the terminal closes and starts
+again at login.
+
+```bash
+octiqflow status
+octiqflow restart
+octiqflow open
+octiqflow uninstall
+```
+
+Uninstalling the service keeps profiles and transcripts under `~/.octiqflow`.
+Agent CLIs are separate: install any of Claude Code, Codex, or pi.dev that you
+want OctiqFlow to drive.
+
+Project and source: <https://github.com/kyson8101/octiq-flow>

package/bin/octiqflow.cjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+const { main } = require('../lib/cli.cjs');
+
+main(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    console.error(`octiqflow: ${error.message}`);
+    process.exitCode = 1;
+  });

package/lib/cli.cjs

@@ -0,0 +1,171 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { resolveRuntime, runForeground } = require('./runtime.cjs');
+const {
+  installMacService,
+  restartMacService,
+  serviceStatus,
+  uninstallMacService,
+} = require('./service.cjs');
+
+const HELP = `OctiqFlow — agent workflow orchestration in your browser
+
+Usage:
+  octiqflow                     Run in the foreground
+  octiqflow install [options]   Install and start the macOS background service
+  octiqflow uninstall           Remove the macOS background service
+  octiqflow status [options]    Check the service and HTTP endpoint
+  octiqflow restart             Restart the macOS background service
+  octiqflow open [options]      Open the local browser client
+
+Options:
+  --port <number>               HTTP port (default: 1421)
+  --bind <address>              Bind address (default: 127.0.0.1)
+  --no-open                     Do not open a browser after installation
+  -h, --help                    Show this help
+  -v, --version                 Show the package version
+
+Node.js 18 or newer is required. Claude Code, Codex, and pi.dev are detected
+separately; install whichever agent CLIs you want OctiqFlow to drive.
+`;
+
+function packageVersion() {
+  const manifest = path.join(__dirname, '..', 'package.json');
+  return JSON.parse(fs.readFileSync(manifest, 'utf8')).version;
+}
+
+function parseOptions(args) {
+  const options = {
+    port: Number(process.env.OCTIQ_WEB_PORT || 1421),
+    bind: process.env.OCTIQ_WEB_BIND || '127.0.0.1',
+    open: true,
+  };
+  const rest = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === '--port') {
+      const raw = args[++index];
+      if (raw == null) throw new Error('--port needs a value');
+      options.port = Number(raw);
+    } else if (value === '--bind') {
+      const raw = args[++index];
+      if (raw == null) throw new Error('--bind needs a value');
+      options.bind = raw;
+    } else if (value === '--no-open') {
+      options.open = false;
+    } else {
+      rest.push(value);
+    }
+  }
+  if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) {
+    throw new Error('--port must be an integer from 1 to 65535');
+  }
+  return { options, rest };
+}
+
+async function localUrl(port, fetchImpl = fetch) {
+  const origin = `http://127.0.0.1:${port}`;
+  const tokenResponse = await fetchImpl(`${origin}/token`);
+  if (!tokenResponse.ok) throw new Error(`server answered ${tokenResponse.status} at /token`);
+  const token = (await tokenResponse.text()).trim();
+  return `${origin}/?token=${encodeURIComponent(token)}`;
+}
+
+async function waitForUrl(port, options = {}) {
+  const attempts = options.attempts || 30;
+  const delay = options.delay || 250;
+  const fetchImpl = options.fetch || fetch;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      const response = await fetchImpl(`http://127.0.0.1:${port}/healthz`);
+      if (response.ok) return localUrl(port, fetchImpl);
+    } catch (_error) {
+      // launchd has accepted the job but the socket is not ready yet.
+    }
+    await new Promise((resolve) => setTimeout(resolve, delay));
+  }
+  throw new Error(`the service started but did not listen on port ${port}`);
+}
+
+function openBrowser(url, platform = process.platform) {
+  const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+  child.once('error', () => {});
+  child.unref();
+}
+
+async function main(args, dependencies = {}) {
+  const output = dependencies.output || console;
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    output.log(HELP.trimEnd());
+    return 0;
+  }
+  if (args.includes('--version') || args.includes('-v') || args[0] === 'version') {
+    output.log(packageVersion());
+    return 0;
+  }
+
+  const command = args[0] && !args[0].startsWith('-') ? args[0] : 'run';
+  const commandArgs = command === 'run' && args[0] !== 'run' ? args : args.slice(1);
+  const { options, rest } = parseOptions(commandArgs);
+  if (rest.length) throw new Error(`unknown argument: ${rest[0]}`);
+
+  if (command === 'run') {
+    const runtime = (dependencies.resolveRuntime || resolveRuntime)();
+    return (dependencies.runForeground || runForeground)(runtime, [], {
+      env: {
+        OCTIQ_WEB_BIND: options.bind,
+        OCTIQ_WEB_PORT: String(options.port),
+      },
+    });
+  }
+  if (command === 'install') {
+    const runtime = (dependencies.resolveRuntime || resolveRuntime)();
+    const details = (dependencies.installMacService || installMacService)(runtime, {
+      version: packageVersion(),
+      bind: options.bind,
+      port: options.port,
+    });
+    const url = await (dependencies.waitForUrl || waitForUrl)(options.port);
+    output.log(`OctiqFlow ${packageVersion()} is running as a background service.`);
+    output.log(url);
+    output.log(`Logs: ${details.logs}`);
+    if (options.open) (dependencies.openBrowser || openBrowser)(url);
+    return 0;
+  }
+  if (command === 'uninstall') {
+    (dependencies.uninstallMacService || uninstallMacService)();
+    output.log('OctiqFlow background service removed. Your profiles and transcripts were kept.');
+    return 0;
+  }
+  if (command === 'restart') {
+    (dependencies.restartMacService || restartMacService)();
+    const url = await (dependencies.waitForUrl || waitForUrl)(options.port);
+    output.log(`OctiqFlow restarted: ${url}`);
+    return 0;
+  }
+  if (command === 'status') {
+    const installed = (dependencies.serviceStatus || serviceStatus)();
+    let url = null;
+    try {
+      url = await (dependencies.localUrl || localUrl)(options.port);
+    } catch (_error) {
+      // Status reports both facts instead of turning an unavailable endpoint
+      // into an exception that hides whether launchd owns the service.
+    }
+    output.log(`Service: ${installed ? 'installed' : 'not installed'}`);
+    output.log(`Endpoint: ${url || 'not responding'}`);
+    return installed && url ? 0 : 1;
+  }
+  if (command === 'open') {
+    const url = await (dependencies.localUrl || localUrl)(options.port);
+    (dependencies.openBrowser || openBrowser)(url);
+    output.log(url);
+    return 0;
+  }
+  throw new Error(`unknown command: ${command}; run octiqflow --help`);
+}
+
+module.exports = { HELP, localUrl, main, openBrowser, packageVersion, parseOptions, waitForUrl };

package/lib/runtime.cjs

@@ -0,0 +1,66 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const PLATFORM_PACKAGES = Object.freeze({
+  'darwin-arm64': 'octiqflow-darwin-arm64',
+  'darwin-x64': 'octiqflow-darwin-x64',
+  'linux-x64': 'octiqflow-linux-x64',
+  'win32-x64': '@kyson8101/octiqflow-win32-x64',
+});
+
+function packageFor(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`;
+  const packageName = PLATFORM_PACKAGES[key];
+  if (!packageName) {
+    const supported = Object.keys(PLATFORM_PACKAGES).join(', ');
+    throw new Error(`unsupported platform ${key}; supported platforms: ${supported}`);
+  }
+  return packageName;
+}
+
+function resolveRuntime(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const resolve = options.resolve || require.resolve;
+  const exists = options.exists || fs.existsSync;
+  const packageName = packageFor(platform, arch);
+  let manifest;
+  try {
+    manifest = resolve(`${packageName}/package.json`);
+  } catch (_error) {
+    throw new Error(
+      `the runtime package ${packageName} is missing; reinstall without --omit=optional`,
+    );
+  }
+
+  const root = path.dirname(manifest);
+  const binaryName = platform === 'win32' ? 'octiq-server.exe' : 'octiq-server';
+  const binary = path.join(root, 'bin', binaryName);
+  const client = path.join(root, 'bin', 'v2');
+  if (!exists(binary) || !exists(path.join(client, 'index.html'))) {
+    throw new Error(`${packageName} is incomplete; reinstall octiqflow`);
+  }
+  return { packageName, root, binary, client, platform, arch };
+}
+
+function runForeground(runtime, args = [], options = {}) {
+  const spawnImpl = options.spawn || spawn;
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(runtime.binary, args, {
+      cwd: process.cwd(),
+      env: { ...process.env, OCTIQ_WEB: '1', ...(options.env || {}) },
+      stdio: 'inherit',
+    });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      resolve(code == null ? 1 : code);
+    });
+  });
+}
+
+module.exports = { PLATFORM_PACKAGES, packageFor, resolveRuntime, runForeground };

package/lib/service.cjs

@@ -0,0 +1,177 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const LABEL = 'com.kyson.octiqflow.server';
+
+function xml(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function servicePaths(home = os.homedir(), version = 'development') {
+  const base = path.join(home, '.octiqflow');
+  return {
+    base,
+    logs: path.join(base, 'logs'),
+    runtime: path.join(base, 'runtimes', version),
+    plist: path.join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`),
+  };
+}
+
+function plist({ binary, bind, port, home, shell }) {
+  const logs = path.join(home, '.octiqflow', 'logs');
+  const searchPath = [
+    path.join(home, '.local', 'bin'),
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+    '/usr/bin',
+    '/bin',
+    '/usr/sbin',
+    '/sbin',
+  ].join(':');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array><string>${xml(binary)}</string></array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>OCTIQ_WEB</key><string>1</string>
+    <key>OCTIQ_WEB_BIND</key><string>${xml(bind)}</string>
+    <key>OCTIQ_WEB_PORT</key><string>${xml(port)}</string>
+    <key>PATH</key><string>${xml(searchPath)}</string>
+    <key>SHELL</key><string>${xml(shell)}</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${xml(path.join(logs, 'server.log'))}</string>
+  <key>StandardErrorPath</key><string>${xml(path.join(logs, 'server.err.log'))}</string>
+</dict>
+</plist>
+`;
+}
+
+function runLaunchctl(args, options = {}) {
+  const run = options.run || spawnSync;
+  return run('launchctl', args, { encoding: 'utf8', stdio: options.stdio || 'pipe' });
+}
+
+function sleep(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function replaceDirectory(source, destination) {
+  const parent = path.dirname(destination);
+  const temporary = `${destination}.install-${process.pid}-${Date.now()}`;
+  fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+  fs.cpSync(source, temporary, { recursive: true });
+  fs.rmSync(destination, { recursive: true, force: true });
+  fs.renameSync(temporary, destination);
+}
+
+function installMacService(runtime, options = {}) {
+  if ((options.platform || process.platform) !== 'darwin') {
+    throw new Error('background service installation is currently supported on macOS only');
+  }
+  const home = options.home || os.homedir();
+  const version = options.version || 'development';
+  const bind = options.bind || '127.0.0.1';
+  const port = Number(options.port || 1421);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('port must be an integer from 1 to 65535');
+  }
+
+  const paths = servicePaths(home, version);
+  const binDir = path.join(paths.runtime, 'bin');
+  fs.mkdirSync(paths.logs, { recursive: true, mode: 0o700 });
+  fs.mkdirSync(binDir, { recursive: true, mode: 0o700 });
+  const installedBinary = path.join(binDir, 'octiq-server');
+  fs.copyFileSync(runtime.binary, installedBinary);
+  fs.chmodSync(installedBinary, 0o755);
+  replaceDirectory(runtime.client, path.join(binDir, 'v2'));
+
+  fs.mkdirSync(path.dirname(paths.plist), { recursive: true });
+  const body = plist({
+    binary: installedBinary,
+    bind,
+    port,
+    home,
+    shell: process.env.SHELL || '/bin/zsh',
+  });
+  const temporaryPlist = `${paths.plist}.install-${process.pid}`;
+  fs.writeFileSync(temporaryPlist, body, { mode: 0o600 });
+  fs.renameSync(temporaryPlist, paths.plist);
+
+  const domain = `gui/${options.uid == null ? process.getuid() : options.uid}`;
+  runLaunchctl(['bootout', `${domain}/${LABEL}`], options);
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    if (runLaunchctl(['print', `${domain}/${LABEL}`], options).status !== 0) break;
+    sleep(250);
+  }
+  let started = false;
+  let lastError = '';
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const result = runLaunchctl(['bootstrap', domain, paths.plist], options);
+    if (result.status === 0) {
+      started = true;
+      break;
+    }
+    lastError = (result.stderr || result.stdout || '').trim();
+    sleep(500);
+  }
+  if (!started) {
+    throw new Error(`launchd could not start OctiqFlow${lastError ? `: ${lastError}` : ''}`);
+  }
+  return { ...paths, binary: installedBinary, bind, port };
+}
+
+function uninstallMacService(options = {}) {
+  if ((options.platform || process.platform) !== 'darwin') {
+    throw new Error('background service installation is currently supported on macOS only');
+  }
+  const home = options.home || os.homedir();
+  const paths = servicePaths(home);
+  const domain = `gui/${options.uid == null ? process.getuid() : options.uid}`;
+  runLaunchctl(['bootout', `${domain}/${LABEL}`], options);
+  fs.rmSync(paths.plist, { force: true });
+  return paths.plist;
+}
+
+function serviceStatus(options = {}) {
+  if ((options.platform || process.platform) !== 'darwin') return false;
+  const domain = `gui/${options.uid == null ? process.getuid() : options.uid}`;
+  return runLaunchctl(['print', `${domain}/${LABEL}`], options).status === 0;
+}
+
+function restartMacService(options = {}) {
+  if ((options.platform || process.platform) !== 'darwin') {
+    throw new Error('background service installation is currently supported on macOS only');
+  }
+  const domain = `gui/${options.uid == null ? process.getuid() : options.uid}`;
+  const result = runLaunchctl(['kickstart', '-k', `${domain}/${LABEL}`], options);
+  if (result.status !== 0) {
+    throw new Error('OctiqFlow service is not installed');
+  }
+}
+
+module.exports = {
+  LABEL,
+  installMacService,
+  plist,
+  restartMacService,
+  servicePaths,
+  serviceStatus,
+  uninstallMacService,
+  xml,
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "octiqflow",
+  "version": "0.1.52",
+  "description": "Agent workflow orchestrator with real browser terminals",
+  "bin": {
+    "octiqflow": "bin/octiqflow.cjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "octiqflow-darwin-arm64": "0.1.52",
+    "octiqflow-darwin-x64": "0.1.52",
+    "octiqflow-linux-x64": "0.1.52",
+    "@kyson8101/octiqflow-win32-x64": "0.1.52"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kyson8101/octiq-flow.git"
+  },
+  "homepage": "https://github.com/kyson8101/octiq-flow#readme",
+  "bugs": "https://github.com/kyson8101/octiq-flow/issues",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}