@factiii/runner 0.10.1 → 0.11.0

package/index/index.js

@@ -6915,9 +6915,9 @@ var require_dist = __commonJS({
   }
 });
 
-// ../../node_modules/content-type/index.js
+// ../../node_modules/@modelcontextprotocol/sdk/node_modules/content-type/index.js
 var require_content_type = __commonJS({
-  "../../node_modules/content-type/index.js"(exports2) {
+  "../../node_modules/@modelcontextprotocol/sdk/node_modules/content-type/index.js"(exports2) {
     "use strict";
     var PARAM_REGEXP = /; *([!#$%&'*+.^_`|~0-9A-Za-z-]+) *= *("(?:[\u000b\u0020\u0021\u0023-\u005b\u005d-\u007e\u0080-\u00ff]|\\[\u000b\u0020-\u00ff])*"|[!#$%&'*+.^_`|~0-9A-Za-z-]+) */g;
     var TEXT_REGEXP = /^[\u000b\u0020-\u007e\u0080-\u00ff]+$/;
@@ -92495,14 +92495,20 @@ function text(value) {
   return { content: [{ type: "text", text: value }] };
 }
 function makeTool(t) {
+  const args = t.args.strict();
   return {
     name: t.name,
     description: t.description,
     inputSchema: t.inputSchema,
-    handle: (raw) => t.run(t.args.parse(raw))
+    handle: (raw) => t.run(args.parse(raw))
   };
 }
-var objectSchema = (properties, required2) => ({ type: "object", properties, required: required2 });
+var objectSchema = (properties, required2) => ({
+  type: "object",
+  properties,
+  required: required2,
+  additionalProperties: false
+});
 function buildTools(store2, spaceSlug, fileBaseUrl) {
   return [
     makeTool({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factiii/runner",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Factiii Runner, run Board AI agents on a machine you control. Pairs with the Factiii web/mobile clients over WebRTC.",
   "license": "ISC",
   "keywords": [
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist/cli.js",
+    "plugin/",
     "index/index.js",
     "index/image-package.json",
     "vendor/frpc-linux-amd64",

package/plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "factiii-runner",
+  "description": "Everything a factiii runner hands its CLIs: session status hooks and workspace skills.",
+  "owner": { "name": "Factiii" },
+  "plugins": [
+    {
+      "name": "factiii",
+      "source": "./factiii",
+      "description": "Board terminal integration for claude and codex."
+    }
+  ]
+}

package/plugin/factiii/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "factiii",
+  "version": "0.1.0",
+  "description": "Board terminal integration: reports what the agent is doing to the session's status dot, and ships the skills a factiii workspace provides.",
+  "author": { "name": "Factiii" },
+  "homepage": "https://factiii.com"
+}

package/plugin/factiii/bin/factiii-secrets

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * factiii-secrets - run a command with this space's stored secrets injected.
+ *
+ * A PROXY, never a carrier. This process asks the runner to run the command;
+ * the runner is what holds the decrypted values, execs the command, and sends
+ * back output already redacted against them. Nothing secret ever enters this
+ * process, so nothing secret is visible to whatever spawned it - which is the
+ * whole point, because what spawns it is an AI agent.
+ *
+ * Finding the runner doubles as the gate: this plugin installs globally, so
+ * outside a factiii space there is no socket and the command says so rather
+ * than hanging.
+ */
+'use strict';
+
+const fs = require('fs');
+const net = require('net');
+const path = require('path');
+
+const SOCK_NAME = 'secrets.sock';
+/** Denial is not a command failure: a distinct code lets a script tell "the
+ *  owner said no" from "the command ran and failed". */
+const EXIT_DENIED = 77;
+/** Nothing ran at all - no socket, no runner, bad usage. */
+const EXIT_UNAVAILABLE = 3;
+
+function usage() {
+  process.stderr.write(
+    [
+      'usage:',
+      '  factiii-secrets run -- <command...>   run it with the declared secrets injected',
+      '  factiii-secrets list                  print the declared key NAMES (never values)',
+      ''
+    ].join('\n')
+  );
+}
+
+/** `<spaceDir>/state/secrets.sock`. The env var is what the runner sets on
+ *  every spawn; the walk-up covers a caller that changed the working
+ *  directory to somewhere the runner did not choose. */
+function findSocket() {
+  const fromEnv = process.env.FACTIII_SECRETS_SOCK;
+  if (fromEnv) return fromEnv;
+  let dir = process.cwd();
+  while (dir && dir !== path.dirname(dir)) {
+    const candidate = path.join(dir, 'state', SOCK_NAME);
+    try {
+      if (fs.statSync(candidate).isSocket()) return candidate;
+    } catch {
+      // Not here; keep walking.
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Rebuild one shell word.
+ *
+ * The runner runs the command through a login shell and shows it to the owner
+ * verbatim for authorization, so what we send has to mean exactly what the
+ * caller's argv meant. Single quotes make every character literal; the only
+ * thing that cannot appear inside them is a single quote, which is spliced.
+ * Words that need no quoting are left bare so the authorization card stays
+ * readable.
+ */
+function shellQuote(word) {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(word)) return word;
+  return `'${word.split("'").join(`'\\''`)}'`;
+}
+
+/** One NDJSON request, its stream of replies handled by `onMessage`. */
+function request(socketPath, payload, onMessage) {
+  return new Promise((resolve) => {
+    const conn = net.createConnection(socketPath);
+    let buffer = '';
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      conn.end();
+      resolve(code);
+    };
+
+    conn.on('connect', () => conn.write(`${JSON.stringify(payload)}\n`));
+    conn.on('data', (chunk) => {
+      buffer += chunk.toString('utf-8');
+      let newline = buffer.indexOf('\n');
+      while (newline !== -1) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (line.trim()) {
+          let message;
+          try {
+            message = JSON.parse(line);
+          } catch {
+            // A malformed frame is the runner's bug, not the caller's; there
+            // is nothing useful to do with half a message.
+            message = null;
+          }
+          if (message) {
+            const code = onMessage(message);
+            if (typeof code === 'number') finish(code);
+          }
+        }
+        newline = buffer.indexOf('\n');
+      }
+    });
+    conn.on('error', (err) => {
+      // The path can be known and still have nothing listening: the store is
+      // served only while a deploy run is in progress, and a creator session
+      // drafting a skill is the common case of asking outside one.
+      const why =
+        err.code === 'ENOENT' || err.code === 'ECONNREFUSED'
+          ? 'the secrets store is not being served right now. It is available during a deploy run'
+          : `cannot reach the runner (${err.message})`;
+      process.stderr.write(`factiii-secrets: ${why}.\n`);
+      finish(EXIT_UNAVAILABLE);
+    });
+    // Closed with no verdict: the runner died, or the deploy run was
+    // cancelled mid-command. Either way nothing was reported as finished.
+    conn.on('close', () => finish(EXIT_UNAVAILABLE));
+  });
+}
+
+async function main() {
+  const [op, ...rest] = process.argv.slice(2);
+
+  if (!op || op === '-h' || op === '--help') {
+    usage();
+    return op ? 0 : EXIT_UNAVAILABLE;
+  }
+  if (op !== 'run' && op !== 'list') {
+    process.stderr.write(`factiii-secrets: unknown command "${op}".\n`);
+    usage();
+    return EXIT_UNAVAILABLE;
+  }
+
+  const socketPath = findSocket();
+  if (!socketPath) {
+    process.stderr.write(
+      'factiii-secrets: no secrets store is reachable here. This command works inside a factiii space while a deploy run is active.\n'
+    );
+    return EXIT_UNAVAILABLE;
+  }
+
+  if (op === 'list') {
+    return request(socketPath, { op: 'list' }, (message) => {
+      if (message.type === 'keys') {
+        process.stdout.write(`${message.keys.join('\n')}\n`);
+        return 0;
+      }
+      if (message.type === 'error') {
+        process.stderr.write(`factiii-secrets: ${message.message}\n`);
+        return EXIT_UNAVAILABLE;
+      }
+    });
+  }
+
+  // `--` is optional but documented: it is what stops the caller's own flags
+  // (-e, --prod) from being read as ours.
+  const argv = rest[0] === '--' ? rest.slice(1) : rest;
+  if (!argv.length) {
+    process.stderr.write('factiii-secrets: run needs a command.\n');
+    usage();
+    return EXIT_UNAVAILABLE;
+  }
+
+  const command = argv.map(shellQuote).join(' ');
+  return request(
+    socketPath,
+    { op: 'run', command, cwd: process.cwd() },
+    (message) => {
+      if (message.type === 'status') {
+        // stderr, so a caller capturing stdout gets the command's output and
+        // nothing of ours.
+        process.stderr.write(`factiii-secrets: ${message.text}\n`);
+        return;
+      }
+      if (message.type === 'output') {
+        process.stdout.write(message.chunk);
+        return;
+      }
+      if (message.type === 'denied') {
+        process.stderr.write(
+          'factiii-secrets: the owner declined to run that command.\n'
+        );
+        return EXIT_DENIED;
+      }
+      if (message.type === 'error') {
+        process.stderr.write(`factiii-secrets: ${message.message}\n`);
+        return EXIT_UNAVAILABLE;
+      }
+      if (message.type === 'exit') return message.code;
+    }
+  );
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`factiii-secrets: ${err && err.message}\n`);
+    process.exitCode = EXIT_UNAVAILABLE;
+  }
+);

package/plugin/factiii/bin/report-state.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Tell the runner what the agent is doing, so the board's status dot reflects
+# it. Called from hooks.json on the events both CLIs share.
+#
+# Everything is derived, nothing is injected. The runner sets a tmux session's
+# environment only when it CREATES the session (`new-session -A -e`), so a var
+# added by a runner upgrade never reaches a session that is already running —
+# which on any real host is most of them. TMUX_PANE is set by tmux itself at
+# pane creation, so it is already there in every session ever started.
+#
+# It doubles as the gate. This plugin installs globally, so its hooks fire on
+# every claude and codex run on this machine; outside a factiii workspace there
+# is no pane and no space redis to find, and this exits having done nothing.
+#
+# Never fails the CLI. A hook that exits non-zero can block the turn it fired
+# on, and a status dot is not worth interrupting someone's work for.
+set -u
+[ -n "${TMUX_PANE:-}" ] || exit 0
+
+# The space's redis sits at <spaceDir>/state/redis.sock and the CLI runs inside
+# that space's tree, so walk up for it. Bounded by reaching the root.
+dir="$PWD"
+sock=""
+while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+  if [ -S "$dir/state/redis.sock" ]; then
+    sock="$dir/state/redis.sock"
+    break
+  fi
+  dir="$(dirname "$dir")"
+done
+[ -n "$sock" ] || exit 0
+
+state="${1:-idle}"
+# The pane is the identity; the runner resolves it to a session. Keeping that
+# mapping on the runner is what stops this script from having to know how tmux
+# sessions are named.
+#
+# SET then PUBLISH: the publish drives live dots, the key lets a subscriber
+# that starts mid-session read where things stand without waiting for a hook.
+# -t 2 so a dead socket costs milliseconds rather than hanging the turn.
+redis-cli -t 2 -s "$sock" set "agent-state:$TMUX_PANE" "$state" >/dev/null 2>&1
+redis-cli -t 2 -s "$sock" publish agent-state "$TMUX_PANE $state" >/dev/null 2>&1
+exit 0

package/plugin/factiii/hooks/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/bin/report-state.sh\" working",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/bin/report-state.sh\" idle",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/bin/report-state.sh\" blocked",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/bin/report-state.sh\" blocked",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/bin/report-state.sh\" idle",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/factiii/skills/factiii-secrets/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: factiii-secrets
+description: Run a command that needs this workspace's stored secrets, with factiii-secrets. TRIGGER when a command needs an API token, deploy credential, database URL or any other secret value, when writing or revising a deploy skill, or whenever an environment variable a step needs appears to be missing.
+---
+
+# factiii-secrets
+
+This machine keeps the workspace's secrets in an encrypted store the owner
+manages. You never hold those values, and you never need to: one command runs
+anything that needs them.
+
+```bash
+factiii-secrets run -- <command...>
+```
+
+It is already on your PATH. Nothing needs installing, and nothing needs
+setting up before you use it.
+
+## What actually happens
+
+You run the command. It blocks. The owner sees the exact command on their
+board, with the keys it will receive, and enters their password to authorize
+it. The runner then decrypts the store for that one command, runs it with the
+values in its environment, and hands you back its output with every secret
+value replaced by `[REDACTED]`. `factiii-secrets` exits with the command's own
+exit code, so `&&`, `||` and `set -e` all behave normally.
+
+The values reach the command and stop there. They are never in your
+environment, never in your context, and never in anything you can read.
+
+## Using it
+
+Write the command exactly as you would without the wrapper, referencing
+secrets as ordinary `$NAME` variables:
+
+```bash
+factiii-secrets run -- vercel deploy --prod --token "$VERCEL_TOKEN"
+factiii-secrets run -- psql "$DATABASE_URL" -f migrations/latest.sql
+factiii-secrets run -- ./scripts/publish.sh
+```
+
+Quote the variables. They expand on the runner's side, once the values are
+present - not in your shell, where they are empty.
+
+Wrap **only** the commands that need a secret. Everything else - builds,
+tests, git, file edits - runs normally, unwrapped, and stays fast because it
+needs no authorization.
+
+```bash
+factiii-secrets list
+```
+
+prints the key NAMES the workspace has declared. Never their values; there is
+no command that prints a value, on purpose.
+
+## Things that will waste your time
+
+- **Do not check whether these variables are set.** They are unset in your
+  shell by design and will stay that way for the whole session. `env`,
+  `printenv`, `test -n "$TOKEN"` and echo-checks all tell you nothing.
+- **Do not report them as missing or stop over them.** An unset declared
+  variable is the security model working. Route the command through
+  `factiii-secrets run` and it gets what it needs.
+- **Do not ask the owner to export them,** write them to a `.env`, or put them
+  in a shell profile or CI config. They are already stored; that is what this
+  command reads.
+- **Never print a value.** If output somehow contains one, do not repeat it.
+
+## Exit codes
+
+- The command's own exit code, when it ran.
+- `77` - the owner declined to authorize it. That is an answer, not a fault:
+  adapt or stop and explain where things stand. Do not retry the same command.
+- `3` - nothing ran. No store is reachable here, or the runner went away.
+
+## Writing a deploy skill
+
+A repo's deploy skill declares every key it needs in
+`.agents/skills/deploy/required-variables.json`, then wraps each step that
+needs one in `factiii-secrets run -- …`. Declare a key exactly when a command
+uses it: never declare one the skill does not use, never use one it does not
+declare. Put no secret value, and no key material, in any file.

package/plugin/factiii/skills/share-a-port/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: share-a-port
+description: Give a port running in this workspace a public HTTPS URL, with factiii-expose. TRIGGER when the user asks to share, expose, preview or publish a local server, wants a link to something running on localhost, or needs an external service to reach a local port.
+---
+
+# share-a-port
+
+This workspace can put a local port on the public internet. Both commands are
+already on your PATH; nothing needs installing.
+
+## Share a port
+
+```bash
+factiii-expose <port> <name>   # e.g. factiii-expose 3000 app
+```
+
+It prints the public URL and returns straight away - the tunnel runs in the
+background and lives until the session ends or you stop it.
+
+- `<name>` may hold letters, numbers and dashes only.
+- Re-running it with the same name replaces that tunnel rather than opening a
+  second one, so it is safe to repeat.
+- Start the server FIRST. A URL for a port nothing is listening on answers
+  with an error, which reads to the user like a broken tunnel.
+
+## Stop sharing
+
+```bash
+factiii-unexpose <name>
+```
+
+## Before you share
+
+The URL is public and unauthenticated: anyone holding the link reaches
+whatever that port serves. Do not expose a service that fronts real
+credentials, customer data, or a database. If you are unsure whether the user
+wants something reachable from outside, ask first.
+
+Always tell the user the URL you got back. They can also see every live
+tunnel, and stop any of them, in the card's Task Manager panel.
+