@ctrl-spc/cs 0.7.0 → 0.7.2

package/dist/panel3/cli.js

@@ -1,83 +1,70 @@
 #!/usr/bin/env node
 /**
- * ═══ AGENT PANEL v3: the `cs3` bin. ═══
+ * ═══ AGENT PANEL v3: the panel's commands, and the harness bin that runs them. ═══
  *
  * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may
- * import it.
+ * import it, but for the one mount `cli-v2/src/index.ts` makes on
+ * `panelCommand`, named in `test/panel3-isolation.contract.test.mjs`.
  *
- * A SEPARATE BIN RATHER THAN A SUBCOMMAND OF `cs`, deliberately: v3 never
- * touches v1's command router, so retiring either generation is deleting a
- * directory and a line of `bin`, not unpicking a switch statement two
- * generations share.
+ * ═══ THE PERSON TYPES `cs`, AND ONLY `cs`. ═══ Lane's ruling (2026-08-24):
+ * nothing the product names may carry a version the person never knew about,
+ * and there is one CLI to launch and sign into. So `say`, `answer` and `show`
+ * are `cs` subcommands, reached through `panelCommand` below, and the `cs3` bin
+ * that used to publish them is gone. The router stays HERE rather than moving
+ * into `index.ts` so that v3 is still one directory to delete: `index.ts` holds
+ * three cases and a single import, not the panel's argument handling.
  *
- * ═══ AND SINCE recovery-1 SLICE 4, `run` IS NOT SOMETHING A PERSON TYPES. ═══
- * Lane's ruling (2026-08-21): a person launches one CLI, `cs start`, and signs
- * into it once. `cs start` now runs the panel's poll loop through `startPanel`,
- * so that is the only launch the product ever names, and `cs3 run` is off the
- * help text above.
- *
- * ═══ IT IS STILL HERE, AND IT IS NOT A SECOND OWNER OF THE LOOP. ═══ There is
- * one `run()` in `run.ts` with two callers. This one signs in from
- * `CTRL_SPC_V3_EMAIL` / `CTRL_SPC_V3_PASSWORD`, which is what lets
- * `test/panel3-acceptance.mjs` and the three walk scripts stand a daemon up
- * against their own isolated account and their own working copy without touching
- * the installed CLI's `session.json` or its presence. Deleting it would mean
- * rebuilding that isolation inside `cs start`, which is a launch path the tests
- * would then own. DO NOT PUT IT BACK IN THE HELP TEXT.
+ * ═══ AND `run` IS STILL NOT SOMETHING A PERSON TYPES. ═══ `cs start` runs the
+ * panel's poll loop through `startPanel`, so that is the only launch the product
+ * names. `run` is reachable only by running this file directly, which is what
+ * `test/panel3-acceptance.mjs` and the walk scripts do. It signs in from
+ * `CTRL_SPC_V3_EMAIL` / `CTRL_SPC_V3_PASSWORD`, which is what lets them stand a
+ * daemon up against their own isolated account and their own working copy
+ * without touching the installed CLI's `session.json` or its presence. There is
+ * one `run()` in `run.ts` with two callers, not two copies of the loop. DO NOT
+ * PUT IT IN `cs`.
  *
  * ═══ A FAILURE EXITS NON-ZERO AND SAYS WHY, ALWAYS. ═══ Every read in `show`
- * and every write in `say` either returns its rows or throws, and this is the
- * only handler. Nothing here converts a failure into an empty result, because a
- * command whose whole job is observation is worthless the first time silence can
- * mean either "nothing is there" or "the read failed", and a `say` that exited
- * zero without writing would be an acknowledgement of nothing.
+ * and every write in `say` either returns its rows or throws, and the two
+ * handlers below are the only ones. Nothing here converts a failure into an
+ * empty result, because a command whose whole job is observation is worthless
+ * the first time silence can mean either "nothing is there" or "the read
+ * failed", and a `say` that exited zero without writing would be an
+ * acknowledgement of nothing.
  */
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { answer } from './answer.js';
 import { run } from './run.js';
 import { say } from './say.js';
 import { show } from './show.js';
-const HELP = `cs3 — CTRL+SPC agent panel v3
-
-  cs3 say "<text>"              Start a card and put your message on it
-  cs3 say --project <p> "<text>"  Start it filed under that project (id or name)
-  cs3 say --card <id> "<text>"  Add a message to a card you already have
-  cs3 answer <id> "<text>"      Answer a question a card is waiting on you for
-  cs3 show                      Every card
-  cs3 show <id>                 One card in full, or one run with its brief and report
-  cs3 help                      Show this help
-
-This machine answers cards when \`cs start\` is running. These commands are the
-terminal's view of the same record.
-
-Acts as CTRL_SPC_V3_EMAIL / CTRL_SPC_V3_PASSWORD, against the hosted project
-by default. Point it at a local stack with:
-  CTRL_SPC_SUPABASE_URL=http://127.0.0.1:54321
-  CTRL_SPC_SUPABASE_KEY=<the local publishable key from \`supabase status\`>
-`;
-async function main() {
-    const command = process.argv[2];
+/**
+ * One panel command, given the whole tail of `process.argv` from the command
+ * word on. `cs` routes `say`, `answer` and `show` here; running this file
+ * directly reaches `run` as well.
+ */
+export async function panelCommand(argv) {
+    const command = argv[0];
     switch (command) {
         case 'say':
-            return say(process.argv.slice(3));
+            return say(argv.slice(1));
         case 'answer':
-            return answer(process.argv.slice(3));
+            return answer(argv.slice(1));
         case 'run':
-            return run(process.argv.slice(3));
+            return run(argv.slice(1));
         case 'show':
-            return show(process.argv[3]);
-        case undefined:
-        case 'help':
-        case '--help':
-        case '-h':
-            console.log(HELP);
-            return;
+            return show(argv[1]);
         default:
-            console.error(`Unknown command: ${command}\n`);
-            console.log(HELP);
-            process.exitCode = 1;
+            throw new Error(`unknown command: ${command ?? '(none)'}`);
     }
 }
-main().catch((err) => {
-    console.error(`cs3: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-});
+/* THE HARNESS ENTRY, AND IT MUST NOT FIRE WHEN `cs` IMPORTS `panelCommand`.
+   Both sides go through `realpathSync` because the installed CLI is reached
+   through a symlinked bin, and comparing the raw argument to the module path
+   would make this file two different files depending on how it was reached. */
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+    panelCommand(process.argv.slice(2)).catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}

package/dist/panel3/client.js

@@ -16,14 +16,23 @@
  * copying it a third time.
  *
  * ---------------------------------------------------------------------------
- * WHY IT SIGNS IN EVERY TIME INSTEAD OF READING THE STORED SESSION.
+ * WHY A SESSION OF ITS OWN, AND WHY THE STORED ONE IS READ THE WAY IT IS.
  *
  * The installed CLI keeps one `session.json` on this machine and its long-lived
  * daemon holds the access token that file names. A second process that reads it
- * and lets the client refresh writes a ROTATED token back over the same file,
- * and the daemon's token stops working. So v3 takes a fresh session of its own,
- * in memory, and never touches the file: `persistSession: false`, and no v3
- * client has any storage to write a rotated token into.
+ * and lets the client REFRESH writes a ROTATED token back over the same file,
+ * and the daemon's token stops working. So when credentials are given, v3 takes
+ * a fresh session of its own, in memory, and never touches the file:
+ * `persistSession: false`, and no v3 client has any storage to write a rotated
+ * token into.
+ *
+ * ═══ AND WITH NO CREDENTIALS IT READS THAT FILE, BECAUSE THE PERSON TYPES
+ *     `cs`. ═══ `say`, `answer` and `show` are `cs` subcommands, and a person
+ * who ran `cs login` has no v3 environment set and must not be asked to sign in
+ * twice. `storedSessionClient` below is that read, in the one shape that cannot
+ * rotate anything: the access token on a header, no auth session, no refresh
+ * token, nothing written back. The hazard above is about REFRESHING against
+ * that file, not about reading it.
  *
  * ═══ THAT IS NOW TRUE OF THE COMMANDS AND NOT OF THE PANEL, AND THE DIFFERENCE
  *     IS THE WORD "PROCESS". ═══ recovery-1 Slice 4: `cs start` runs the poll
@@ -35,9 +44,9 @@
  * token. `signedInClient` must never be called from that path, because taking a
  * session of its own there is what would recreate the race indoors.
  *
- * So this function now serves `show`, `say`, `answer`, and `cs3 run` as the
- * acceptance harness's isolated entry — every one of them a process that is NOT
- * the installed daemon, which is exactly the set the paragraph above describes.
+ * So this function now serves `show`, `say`, `answer`, and the acceptance
+ * harness's isolated `run` entry — every one of them a process that is NOT the
+ * installed daemon, which is exactly the set the paragraph above describes.
  *
  * ---------------------------------------------------------------------------
  * ═══ AND THE DAEMON'S CLIENT REFRESHES, WHILE A ONE-SHOT COMMAND'S DOES NOT.
@@ -45,8 +54,8 @@
  *
  * `autoRefreshToken` was off for every v3 client, which is right for `show`,
  * `say` and `answer` — each signs in, does one thing and exits, long inside the
- * access token's lifetime — and WRONG for `cs3 run`, which holds one client for
- * as long as the daemon lives and hands that same client to every tool call an
+ * access token's lifetime — and WRONG for the harness's `run`, which holds one
+ * client for as long as the daemon lives and hands that same client to every tool call an
  * agent makes. Past the token's TTL every poll and every in-flight tool call
  * would start failing, and the card would sit working with a daemon that could
  * no longer read or write anything.
@@ -75,8 +84,9 @@
  * published (`"files": ["dist"]`, `"access": "public"`), and `dist/` is
  * committed, so a literal password here is one `npm publish` away from the
  * public registry — a harm about DISTRIBUTION that the loopback guard below,
- * which is about where a request is SENT, does nothing to prevent. So there is
- * no fallback: unset means refuse, and say where to get them.
+ * which is about where a request is SENT, does nothing to prevent. So no
+ * password is ever defaulted: unset falls through to the stored `cs login`
+ * session, and with neither the command refuses and says what to do.
  *
  * ---------------------------------------------------------------------------
  * ═══ THE LOOPBACK-ONLY GUARD IS GONE, AND THIS IS THE EDIT IT ASKED FOR. ═══
@@ -107,6 +117,7 @@
  */
 import { createClient } from '@supabase/supabase-js';
 import { SUPABASE_URL, SUPABASE_KEY } from '../env.js';
+import { readSession } from '../config.js';
 /**
  * How a v3 client holds its session, for the two lifetimes v3 has.
  *
@@ -122,6 +133,34 @@ export const sessionOptions = (living) => ({
        the token's lifetime, and the daemon does not. */
     autoRefreshToken: living,
 });
+/**
+ * ═══ THE PERSON SIGNED IN ONCE, WITH `cs login`, AND `cs say` MUST NOT ASK
+ *     AGAIN. ═══
+ *
+ * `say`, `answer` and `show` are `cs` subcommands, so the person who ran
+ * `cs login` types them with no environment set at all. This is that session,
+ * and it is read in the one shape that CANNOT rotate the token the daemon is
+ * holding: the stored access token goes on the Authorization header, there is no
+ * auth session on the client, no refresh token is handed over, and nothing is
+ * ever written back to `session.json`. A rotation here is exactly the failure
+ * the header above describes, and the header cannot happen if no client in this
+ * process ever holds a refresh token.
+ *
+ * An expired access token surfaces as the request's own 401 through
+ * `returned()`, which is the truthful failure: `cs start` refreshes the file
+ * this reads, so a person whose machine is online has a live token.
+ */
+function storedSessionClient() {
+    const stored = readSession();
+    if (!stored?.access_token) {
+        throw new Error('not signed in. Run `cs login`, or set CTRL_SPC_V3_EMAIL and CTRL_SPC_V3_PASSWORD to the '
+            + `account this command should act as at ${SUPABASE_URL}`);
+    }
+    return createClient(SUPABASE_URL, SUPABASE_KEY, {
+        auth: sessionOptions(false),
+        global: { headers: { Authorization: `Bearer ${stored.access_token}` } },
+    });
+}
 /**
  * @param living whether this client outlives its access token. The daemon's
  * does; every one-shot command's does not.
@@ -129,10 +168,8 @@ export const sessionOptions = (living) => ({
 export async function signedInClient(living = false) {
     const email = process.env.CTRL_SPC_V3_EMAIL;
     const password = process.env.CTRL_SPC_V3_PASSWORD;
-    if (!email || !password) {
-        throw new Error('set CTRL_SPC_V3_EMAIL and CTRL_SPC_V3_PASSWORD to the account this command '
-            + `should act as at ${SUPABASE_URL}`);
-    }
+    if (!email || !password)
+        return storedSessionClient();
     const client = createClient(SUPABASE_URL, SUPABASE_KEY, { auth: sessionOptions(living) });
     const { data, error } = await client.auth.signInWithPassword({ email, password });
     // Truthfully, and naming both halves of what was attempted: a wrong password

package/dist/panel3/presence.js

@@ -9,7 +9,7 @@ import { returned } from './client.js';
 export const LISTENING_WINDOW_MS = 15_000;
 /** Is this machine still listening?
  *
- *  THE ONE PREDICATE, shared by `cs3 show` and the panel, so the two screens
+ *  THE ONE PREDICATE, shared by `cs show` and the panel, so the two screens
  *  cannot disagree about whether anything can pick a card up.
  *
  *  ═══ IT TAKES THE ROW, NOT A TIMESTAMP, BECAUSE FRESHNESS IS NO LONGER THE