@factiii/runner 0.11.0 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factiii/runner",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Factiii Runner, run Board AI agents on a machine you control. Pairs with the Factiii web/mobile clients over WebRTC.",
   "license": "ISC",
   "keywords": [

package/plugin/factiii/bin/factiii-secrets

@@ -2,11 +2,12 @@
 /**
  * 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.
+ * A PROXY, never a carrier. This process asks the runner to run the command
+ * and names the keys that command needs; the runner is what holds the
+ * decrypted values, execs the command with just those in its env, and sends
+ * back output already redacted. 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
@@ -29,13 +30,74 @@ 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)',
+      '  factiii-secrets run --key NAME [--key NAME]... -- <command...>',
+      '        run it with the values for exactly those keys in its environment',
+      '  factiii-secrets list',
+      '        print the key NAMES the store holds, and their status (never values)',
+      '',
+      'Only the keys you name are injected. --key takes one name, repeats, and',
+      'accepts a comma-separated list. Naming none runs the command with no',
+      'secrets at all.',
       ''
     ].join('\n')
   );
 }
 
+/** What a shell variable may be called, and so what the runner will accept. */
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Split `--key` out of the caller's argv.
+ *
+ * Only the flags BEFORE the command are ours: everything from the first
+ * non-flag word (or from `--`) belongs to the command, which may well have a
+ * `--key` of its own.
+ */
+function parseKeys(argv) {
+  const keys = [];
+  let i = 0;
+  for (; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') {
+      i += 1;
+      break;
+    }
+    let raw;
+    if (arg === '--key') {
+      i += 1;
+      if (i >= argv.length) return { error: '--key needs a name.' };
+      raw = argv[i];
+    } else if (arg.startsWith('--key=')) {
+      raw = arg.slice('--key='.length);
+    } else {
+      break;
+    }
+    for (const name of raw.split(',')) {
+      const key = name.trim();
+      if (!key) continue;
+      if (!KEY_PATTERN.test(key)) {
+        return { error: `"${key}" is not a valid key name.` };
+      }
+      if (!keys.includes(key)) keys.push(key);
+    }
+  }
+  return { keys, rest: argv.slice(i) };
+}
+
+/** `NAME   status` rows, aligned, so a long store stays readable. */
+function formatKeys(entries) {
+  const width = entries.reduce((max, e) => Math.max(max, e.key.length), 0);
+  return entries
+    .map((entry) => {
+      const status = [
+        entry.stored ? 'set' : 'not set',
+        entry.declared ? 'declared' : 'undeclared'
+      ].join(', ');
+      return `${entry.key.padEnd(width)}  ${status}`;
+    })
+    .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. */
@@ -108,18 +170,18 @@ function request(socketPath, payload, onMessage) {
       }
     });
     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.
+      // The path can be known and still have nothing listening: the space is
+      // down, or still provisioning. The store is served for as long as the
+      // space is up now, so this is a state to wait out, not a place to be.
       const why =
         err.code === 'ENOENT' || err.code === 'ECONNREFUSED'
-          ? 'the secrets store is not being served right now. It is available during a deploy run'
+          ? 'the secrets store is not being served right now. The space serves it whenever it is up, so this usually means it is still starting'
           : `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.
+    // Closed with no verdict: the runner died, or the work was cancelled
+    // mid-command. Either way nothing was reported as finished.
     conn.on('close', () => finish(EXIT_UNAVAILABLE));
   });
 }
@@ -140,7 +202,7 @@ async function main() {
   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'
+      'factiii-secrets: no secrets store is reachable here. This command works inside a session a factiii runner started.\n'
     );
     return EXIT_UNAVAILABLE;
   }
@@ -148,7 +210,13 @@ async function main() {
   if (op === 'list') {
     return request(socketPath, { op: 'list' }, (message) => {
       if (message.type === 'keys') {
-        process.stdout.write(`${message.keys.join('\n')}\n`);
+        // `entries` carries the status. An older runner sends names only, and
+        // there is no status to infer from them - printing a bare list says
+        // less than inventing a "set, declared" nobody vouched for.
+        const rows = Array.isArray(message.entries)
+          ? formatKeys(message.entries)
+          : (message.keys || []).join('\n');
+        if (rows) process.stdout.write(`${rows}\n`);
         return 0;
       }
       if (message.type === 'error') {
@@ -158,19 +226,42 @@ async function main() {
     });
   }
 
-  // `--` 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;
+  // `--` ends our flags and starts the command. It is optional - the first
+  // word that is not a `--key` also ends them - but it is what keeps a command
+  // of its own beginning with `--key`/`-e`/`--prod` from being read as ours.
+  const parsed = parseKeys(rest);
+  if (parsed.error) {
+    process.stderr.write(`factiii-secrets: ${parsed.error}\n`);
+    usage();
+    return EXIT_UNAVAILABLE;
+  }
+  const argv = parsed.rest;
   if (!argv.length) {
     process.stderr.write('factiii-secrets: run needs a command.\n');
     usage();
     return EXIT_UNAVAILABLE;
   }
+  // Naming no key is allowed, not corrected: the wrapper then buys nothing, so
+  // say so once rather than guess at a scope the caller did not ask for.
+  if (!parsed.keys.length) {
+    process.stderr.write(
+      'factiii-secrets: no --key given, so this command gets no secrets. Run `factiii-secrets list` for the names.\n'
+    );
+  }
 
   const command = argv.map(shellQuote).join(' ');
   return request(
     socketPath,
-    { op: 'run', command, cwd: process.cwd() },
+    {
+      op: 'run',
+      command,
+      cwd: process.cwd(),
+      keys: parsed.keys,
+      // Proves which session is asking. The runner sets it on every session it
+      // spawns; a caller it did not spawn has none and is refused rather than
+      // put in front of the owner as an anonymous password prompt.
+      token: process.env.FACTIII_SECRETS_TOKEN || ''
+    },
     (message) => {
       if (message.type === 'status') {
         // stderr, so a caller capturing stdout gets the command's output and

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

@@ -10,7 +10,7 @@ manages. You never hold those values, and you never need to: one command runs
 anything that needs them.
 
 ```bash
-factiii-secrets run -- <command...>
+factiii-secrets run --key NAME -- <command...>
 ```
 
 It is already on your PATH. Nothing needs installing, and nothing needs
@@ -18,30 +18,54 @@ 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.
+You run the command. It blocks. The owner gets a prompt wherever they are -
+web or phone - naming your session, the exact command, and the keys you asked
+for, and enters their password to authorize it.
+The runner then decrypts the store for that one command, runs it with **only
+those keys** 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.
 
+## Naming the keys
+
+`--key` is how a command says what it needs. Only the keys you name are
+injected; the rest of the store stays shut. **A command that names no key gets
+no secrets** - the wrapper does nothing for it.
+
+Name one key per flag, repeat the flag, or pass a comma-separated list. All
+three of these ask for the same two keys:
+
+```bash
+factiii-secrets run --key AWS_ACCESS_KEY_ID --key AWS_SECRET_ACCESS_KEY -- ...
+factiii-secrets run --key=AWS_ACCESS_KEY_ID --key=AWS_SECRET_ACCESS_KEY -- ...
+factiii-secrets run --key AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY -- ...
+```
+
+Every `--key` must come BEFORE the `--`. After it, the words are the command's
+own, so a command with a `--key` flag of its own is safe.
+
 ## Using it
 
 Write the command exactly as you would without the wrapper, referencing
-secrets as ordinary `$NAME` variables:
+secrets as ordinary `$NAME` variables, and name every key it will read:
 
 ```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
+factiii-secrets run --key VERCEL_TOKEN -- vercel deploy --prod --token "$VERCEL_TOKEN"
+factiii-secrets run --key DATABASE_URL -- psql "$DATABASE_URL" -f migrations/latest.sql
+factiii-secrets run --key NPM_TOKEN --key GH_TOKEN -- ./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.
 
+A script reads keys its command line never mentions - that last example. Name
+what the SCRIPT reads, not what you can see in the command. Get it wrong and
+the variable is simply empty inside the script; the runner tells you which
+name it could not find.
+
 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.
@@ -50,8 +74,18 @@ needs no authorization.
 factiii-secrets list
 ```
 
-prints the key NAMES the workspace has declared. Never their values; there is
-no command that prints a value, on purpose.
+prints the key NAMES this workspace has, whether the store actually holds a
+value for each, and whether the deploy contract declares it:
+
+```
+DATABASE_URL   set, declared
+EXPO_TOKEN     not set, declared
+OLD_TOKEN      set, undeclared
+```
+
+Never their values; there is no command that prints a value, on purpose. Use
+it when you are unsure what a key is called - guessing a name gets you an
+empty variable, not the value.
 
 ## Things that will waste your time
 
@@ -60,7 +94,7 @@ no command that prints a value, on purpose.
   `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.
+  `factiii-secrets run --key <NAME>` 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.
@@ -73,10 +107,18 @@ no command that prints a value, on purpose.
   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.
 
+It works from any session the runner started - a terminal, a card session, a
+release - not only during a deploy. A caller the runner did NOT start is
+refused before the owner is ever prompted, so running the CLI from a shell of
+your own does not work, and no amount of retrying changes that.
+
 ## 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.
+needs one in `factiii-secrets run --key <NAME> -- …`, naming exactly the keys
+that step reads. Declare a key exactly when a command uses it: never declare
+one the skill does not use, never use one it does not declare. A step asks for
+the keys IT needs, not for every key the skill declares - that per-step scope
+is what the owner sees and authorizes. Put no secret value, and no key
+material, in any file.