@factiii/runner 0.13.1 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@factiii/runner",
3
- "version": "0.13.1",
3
+ "version": "0.14.1",
4
4
  "description": "Factiii Runner, run Board AI agents on a machine you control. Pairs with the Factiii web/mobile clients over WebRTC.",
5
5
  "license": "ISC",
6
6
  "keywords": [
@@ -84,18 +84,30 @@ function parseKeys(argv) {
84
84
  return { keys, rest: argv.slice(i) };
85
85
  }
86
86
 
87
- /** `NAME status` rows, aligned, so a long store stays readable. */
87
+ /**
88
+ * `NAME status title` rows, aligned, each followed by its description
89
+ * indented underneath.
90
+ *
91
+ * The description is the reason to run this at all: a bare name says a
92
+ * credential exists, not which command wants it or what breaks without it.
93
+ * Older runners send no description, so every field here is optional and an
94
+ * undescribed store still prints exactly the rows it used to.
95
+ */
88
96
  function formatKeys(entries) {
89
97
  const width = entries.reduce((max, e) => Math.max(max, e.key.length), 0);
90
- return entries
91
- .map((entry) => {
92
- const status = [
93
- entry.stored ? 'set' : 'not set',
94
- entry.declared ? 'declared' : 'undeclared'
95
- ].join(', ');
96
- return `${entry.key.padEnd(width)} ${status}`;
97
- })
98
- .join('\n');
98
+ const lines = [];
99
+ for (const entry of entries) {
100
+ const status = [
101
+ entry.stored ? 'set' : 'not set',
102
+ entry.declared ? 'declared' : 'undeclared'
103
+ ].join(', ');
104
+ const title = entry.title ? ` ${entry.title}` : '';
105
+ lines.push(`${entry.key.padEnd(width)} ${status}${title}`);
106
+ if (entry.description) {
107
+ lines.push(`${' '.repeat(width + 2)}${entry.description}`);
108
+ }
109
+ }
110
+ return lines.join('\n');
99
111
  }
100
112
 
101
113
  /** `<spaceDir>/state/secrets.sock`. The env var is what the runner sets on
@@ -75,17 +75,25 @@ factiii-secrets list
75
75
  ```
76
76
 
77
77
  prints the key NAMES this workspace has, whether the store actually holds a
78
- value for each, and whether the deploy contract declares it:
78
+ value for each, whether the deploy contract declares it, and what each one is
79
+ FOR:
79
80
 
80
81
  ```
81
- DATABASE_URL set, declared
82
- EXPO_TOKEN not set, declared
82
+ DATABASE_URL set, declared Primary Postgres URL
83
+ The database migrations run against. Points at prod; staging
84
+ has its own.
85
+ EXPO_TOKEN not set, declared Expo access token
86
+ Authenticates the EAS CLI for mobile builds and submits.
83
87
  OLD_TOKEN set, undeclared
84
88
  ```
85
89
 
86
- Never their values; there is no command that prints a value, on purpose. Use
87
- it when you are unsure what a key is called - guessing a name gets you an
88
- empty variable, not the value.
90
+ Never their values; there is no command that prints a value, on purpose.
91
+
92
+ Read this before guessing. It answers both "what is the key called" - a
93
+ guessed name gets you an empty variable, not the value - and "which key does
94
+ this step actually need", which the name alone often does not say. A key with
95
+ no description is simply one nobody has described yet; ask the owner rather
96
+ than inferring a purpose from the name.
89
97
 
90
98
  ## Things that will waste your time
91
99
 
@@ -22,6 +22,31 @@ background and lives until the session ends or you stop it.
22
22
  second one, so it is safe to repeat.
23
23
  - Start the server FIRST. A URL for a port nothing is listening on answers
24
24
  with an error, which reads to the user like a broken tunnel.
25
+ - The URL is HTTPS. `http://` works too, on a different path through the Mini's
26
+ nginx, so prefer the https one you were given.
27
+
28
+ ## Sharing an app, not just a port
29
+
30
+ A web app usually needs two tunnels, and its own config has to name them before
31
+ it is built or booted. A client that still points at `localhost:5001` loads over
32
+ HTTPS and then has every API call blocked as mixed content, which looks like a
33
+ broken deploy rather than a config miss.
34
+
35
+ So: expose both ports first, put those URLs in the app's config (for this repo,
36
+ `NEXT_PUBLIC_SITE_URL` / `NEXT_PUBLIC_API_URL` / `ALLOWED_ORIGINS` in `.env`),
37
+ and only then start the servers. Getting that order wrong costs a restart of
38
+ both.
39
+
40
+ Two more `.env` values matter once the app has logins, and both fail silently:
41
+
42
+ - `COOKIE_DOMAIN` — the two tunnels are different hostnames under one parent, so
43
+ a host-only cookie set on the web host is never sent to the api host. Every
44
+ authenticated call 401s while the UI looks signed in.
45
+ - `NEXT_PUBLIC_COOKIE_PREFIX` — must differ from production's. A preview under
46
+ `*.dev.factiii.com` also receives cookies scoped to `.factiii.com`, so anyone
47
+ logged into the real site sends a same-named cookie that shadows the
48
+ preview's, and signing in simply does not stick. `.env.example` already ships
49
+ a distinct value; keep it distinct.
25
50
 
26
51
  ## Stop sharing
27
52
 
@@ -36,6 +61,12 @@ whatever that port serves. Do not expose a service that fronts real
36
61
  credentials, customer data, or a database. If you are unsure whether the user
37
62
  wants something reachable from outside, ask first.
38
63
 
39
- Always tell the user the URL you got back. They can also see every live
40
- tunnel, and stop any of them, in the card's Task Manager panel.
64
+ Always tell the user the URL you got back.
65
+
66
+ They can also see it themselves, in the card's **Tasks** panel — the button in
67
+ the session header, which lists what the card is running and which ports are
68
+ public. Point them there by that name. **Setup**, the button beside it, is a
69
+ different thing: a fixed log of how the workspace was prepared, which never
70
+ shows running servers. Saying "the task manager" or leaving it unnamed sends
71
+ people to Setup and looks like the tunnel failed.
41
72