anon-pi 0.9.1 → 0.11.0

package/dist/anon-pi.js

@@ -522,13 +522,18 @@ export function resolveLlm(args) {
 /** The machine bare `anon-pi` launches when no `-m` and no config default. */
 export const DEFAULT_MACHINE = 'default';
 /**
- * pi flags that make sense with NO anon-pi project, so `anon-pi <flag> ...`
- * launches pi (at the projects root) and forwards this flag + everything after
- * it verbatim. Two families:
- *  - SESSION selection (`--session <id>` etc.): pi finds the session file (in the
- *    always-mounted machine home) and switches to its own project cwd, so no
- *    project is needed. Mirrors pi's own resume hint (`pi --session <id>`), so
- *    pasting `anon-pi --session <id>` just works.
+ * pi flags anon-pi RECOGNISES in the no-project position, so `anon-pi <flag> ...`
+ * forwards this flag + everything after it verbatim. Three families with three
+ * no-project policies:
+ *  - RESUME (`--session`/`--session-id`/`--resume`/`-r <id>`): resume ONE session
+ *    in place. anon-pi resolves the session's recorded cwd from the host store
+ *    and cds there (isPiResumeFlag / resumeSessionId), so pi resumes cleanly.
+ *    Mirrors pi's own resume hint (`pi --session <id>`), so pasting `anon-pi
+ *    --session <id>` just works.
+ *  - NEEDS-PROJECT (`--fork`, `--continue`/`-c`): REFUSED without a project
+ *    (isPiNeedsProjectFlag) so the (new / newest) conversation never lands in
+ *    the projects root by surprise. Add a project (`.` for the root; created on
+ *    demand): `anon-pi <project> --fork <id>`.
  *  - QUERY (`--list-models`/`--models`): pi prints + exits, no project relevant.
  * For arbitrary pi flags with no project (e.g. `--model x`), use the explicit
  * `anon-pi pi <args…>` passthrough instead.
@@ -550,6 +555,107 @@ const PI_NO_PROJECT_FLAGS = new Set([
 function isPiNoProjectFlag(a) {
     return PI_NO_PROJECT_FLAGS.has(a);
 }
+/**
+ * The RESUME family: session-selecting flags that resume ONE existing session in
+ * place (`--session`/`--session-id <id>`, `--resume`/`-r <id>`). With NO project,
+ * anon-pi resolves the session's recorded cwd from the host session store and
+ * cds THERE (setSessionCwd), so pi resumes cleanly instead of prompting to fork
+ * (its guard fires when the launch cwd differs from the session cwd). With an
+ * explicit project the user is trusted verbatim: anon-pi cds into that project
+ * and lets pi's own fork-prompt guard a mismatch. `--continue`/`--fork` are NOT
+ * here: they need a project (see PI_RESUME_NEEDS_PROJECT_FLAGS).
+ */
+const PI_RESUME_FLAGS = new Set([
+    '--session',
+    '--session-id',
+    '--resume',
+    '-r',
+]);
+/**
+ * Session flags that REQUIRE an explicit project with no-project: `--fork` and
+ * `--continue`/`-c`. `--fork` writes a NEW session and would otherwise land it
+ * silently in the projects ROOT (a surprise); `--continue`/`-c` resumes the
+ * newest session for the launch cwd, so at the root it resolves ambiguously.
+ * anon-pi refuses both without a project (the project may be `.` for the root,
+ * and is created on demand), so where the conversation lands is always explicit.
+ */
+const PI_RESUME_NEEDS_PROJECT_FLAGS = new Set([
+    '--fork',
+    '--continue',
+    '-c',
+]);
+/** True iff `a` is a RESUME-family flag (resolve session cwd; see PI_RESUME_FLAGS). */
+export function isPiResumeFlag(a) {
+    return PI_RESUME_FLAGS.has(a);
+}
+/** True iff `a` is a session flag that needs an explicit project (--fork/--continue). */
+export function isPiNeedsProjectFlag(a) {
+    return PI_RESUME_NEEDS_PROJECT_FLAGS.has(a);
+}
+/**
+ * PURE: the human name a --fork/--continue no-project refusal quotes. `-c` is
+ * spelled as its long form `--continue` in the message (clearer guidance).
+ */
+export function needsProjectFlagName(flag) {
+    return flag === '-c' ? '--continue' : flag;
+}
+/**
+ * PURE: the leading session-id `--fork <id>` / `--continue <id>` accepts, or
+ * undefined. Used only to build a copy-pasteable "add a project" hint in the
+ * refusal (`anon-pi . --fork <id>`); the id is the token right after the flag
+ * when it is not itself another flag.
+ */
+export function resumeFlagId(piArgs) {
+    if (piArgs.length < 2)
+        return undefined;
+    const id = piArgs[1];
+    return id.startsWith('-') ? undefined : id;
+}
+/**
+ * PURE: extract the session id a RESUME-family launch selects, so the CLI can
+ * look its cwd up in the host session store. Scans forwarded pi args for a
+ * resume flag (isPiResumeFlag) and returns the NEXT token when it is an id (not
+ * another flag). Returns undefined when there is no resume flag or no id after
+ * it (e.g. a bare `--resume` picker), in which case the CLI cds nowhere and pi
+ * decides as today.
+ */
+export function resumeSessionId(piArgs) {
+    if (!piArgs)
+        return undefined;
+    for (let i = 0; i < piArgs.length; i++) {
+        if (isPiResumeFlag(piArgs[i])) {
+            const next = piArgs[i + 1];
+            if (next !== undefined && !next.startsWith('-'))
+                return next;
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * PURE: read a pi session's recorded cwd from its session-file HEADER line (the
+ * first JSONL record, `{"type":"session","id":"…","cwd":"/projects/x"}`). This
+ * is the authoritative cwd (what pi keys the conversation by), better than
+ * reversing the lossy `--…--` dir slug. Returns the cwd string, or undefined if
+ * the line is not the expected session header with a non-empty string cwd. The
+ * caller (CLI) supplies the file's first line; this stays pure + testable.
+ */
+export function sessionHeaderCwd(headerLine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(headerLine);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const rec = parsed;
+    if (rec.type !== 'session')
+        return undefined;
+    const cwd = rec.cwd;
+    return typeof cwd === 'string' && cwd.length > 0 ? cwd : undefined;
+}
 /**
  * The explicit pi-passthrough token: `anon-pi pi <args…>` runs pi with the given
  * args and NO project (the general escape hatch for any pi flag). It is a
@@ -672,13 +778,32 @@ export function parseLaunchArgs(args) {
             });
         }
         if (isPiNoProjectFlag(a)) {
-            // A pi flag that needs NO anon-pi project (`--session <id>`/`--continue`/
-            // `--fork` resume by id; `--list-models`/`--models` print + exit). pi
-            // resolves its own cwd (or just prints), so anon-pi launches pi at the
-            // projects root and forwards this flag + everything after it verbatim.
-            // This makes pi's own "To resume: pi --session <id>" hint usable as
-            // `anon-pi --session <id>`. (For ARBITRARY pi flags with no project, use
-            // the explicit `anon-pi pi <args…>` passthrough.)
+            // A pi flag that needs NO anon-pi project (RESUME family `--session <id>`/
+            // `--resume <id>`; `--list-models`/`--models` print + exit). pi resolves
+            // its own cwd (or just prints), so anon-pi launches pi at the projects
+            // root and forwards this flag + everything after it verbatim. For the
+            // RESUME family the CLI then resolves the session's recorded cwd and cds
+            // there so pi resumes in place (no fork prompt). This makes pi's own "To
+            // resume: pi --session <id>" hint usable as `anon-pi --session <id>`. (For
+            // ARBITRARY pi flags with no project, use `anon-pi pi <args…>`.)
+            //
+            // --fork / --continue are REFUSED with no project: they would land a
+            // (new / newest) conversation in the projects ROOT silently. Require an
+            // explicit project (created on demand; `.` for the root) so where the
+            // conversation lands is never a surprise.
+            if (isPiNeedsProjectFlag(a)) {
+                const rest = args.slice(i);
+                const name = needsProjectFlagName(a);
+                const id = resumeFlagId(rest);
+                const example = id
+                    ? `anon-pi <project> ${name} ${id}` +
+                        ` (or \`anon-pi . ${name} ${id}\` for the root)`
+                    : `anon-pi <project> ${name} …` +
+                        ` (or \`anon-pi . ${name} …\` for the root)`;
+                fail(`${name} needs a project so the conversation lands in a known ` +
+                    `directory, not the projects root. Add one (it is created on ` +
+                    `demand): ${example}.`);
+            }
             piArgs = args.slice(i);
             project = undefined;
             i = args.length;
@@ -790,7 +915,14 @@ export function resolveRunPlan(intent, homeFresh) {
     const mounted = nonEmpty(mountParent) !== undefined;
     // Which root the cwd resolves under: /work when --mount, else /projects.
     const rootKind = mounted ? 'mount' : 'projects';
-    const cwd = launchCwd(mode, rootKind, project);
+    // A RESUME-family launch with NO project overrides the default no-project cwd
+    // (the projects root) with the session's own recorded cwd, so pi resumes in
+    // place. Only honoured for a projectless pi launch; a given project always
+    // wins (the user is trusted, pi guards a mismatch).
+    const sessionCwd = nonEmpty(intent.sessionCwd);
+    const cwd = mode === 'pi' && project === undefined && sessionCwd !== undefined
+        ? sessionCwd
+        : launchCwd(mode, rootKind, project);
     const fresh = homeFresh(machine.home);
     const seedVersion = intent.seedVersion ?? SEED_VERSION;
     const directTarget = hostPortKey(llm);
@@ -947,6 +1079,244 @@ export function resolveRunVsStart(intent, kept) {
     const match = kept.find((c) => c.key === want);
     return match ? { action: 'start', ref: match.ref } : { action: 'run' };
 }
+/** PURE: parse a stamped keptContainerKey back into its fields (best-effort). */
+export function parseKeptKey(key) {
+    const out = {
+        machine: '',
+        projectsRoot: '',
+        mountParent: '',
+        cwd: '',
+    };
+    for (const line of key.split('\n')) {
+        const eq = line.indexOf('=');
+        if (eq < 0)
+            continue;
+        const k = line.slice(0, eq);
+        const v = line.slice(eq + 1);
+        if (k === 'machine')
+            out.machine = v;
+        else if (k === 'projectsRoot')
+            out.projectsRoot = v;
+        else if (k === 'mountParent')
+            out.mountParent = v;
+        else if (k === 'cwd')
+            out.cwd = v;
+    }
+    return out;
+}
+/**
+ * PURE: the leaf name of a stamped key's cwd, i.e. the project a container hosts
+ * (`/projects/recon` -> `recon`, `/projects` -> '.', `/work/x` -> `x`, `/root`
+ * -> '' for a bare shell). Used to filter the picker by `<project>` and to label
+ * each row. A root cwd (`/projects`, `/work`) maps to the `.` root token.
+ */
+export function keyProject(fields) {
+    const cwd = fields.cwd;
+    if (cwd === CONTAINER_PROJECTS_ROOT || cwd === CONTAINER_MOUNT_ROOT) {
+        return ROOT_TOKEN;
+    }
+    if (cwd === CONTAINER_HOME_ROOT)
+        return ''; // a bare shell, no project
+    const slash = cwd.lastIndexOf('/');
+    return slash < 0 ? cwd : cwd.slice(slash + 1);
+}
+/**
+ * PURE: pick the RUNNING anon-pi containers a `forward`/`ports` should offer.
+ * Filters the supplied running managed containers (each with its decoded key
+ * fields) to those on `machine`, optionally narrowed to `project` (its leaf cwd
+ * name). With no project, every anon-pi container on the machine qualifies. The
+ * caller resolves 0 (error) / 1 (auto) / many (picker).
+ */
+export function resolveManagedMatches(args) {
+    const { containers, machine, project } = args;
+    return containers.filter((c) => {
+        const f = parseKeptKey(c.key);
+        if (f.machine !== machine)
+            return false;
+        if (project !== undefined && keyProject(f) !== project)
+            return false;
+        return true;
+    });
+}
+/**
+ * PURE: parse a `forward` port token `[<hostPort>:]<jailPort>` (docker/kubectl
+ * host-first order). One port `3001` maps host 3001 -> jail 3001; `8080:3001`
+ * maps host 8080 -> jail 3001. Both sides must be integers in 1..65535. Throws
+ * AnonPiError on a bad shape / out-of-range / extra colon, with copy-pasteable
+ * guidance. `raw` is normalised to `<host>:<jail>` only when they differ, else
+ * the bare jail port, matching netcage's own accepted forms.
+ */
+export function parsePortArg(token) {
+    const bad = (why) => {
+        throw new AnonPiError(`anon-pi: invalid --port ${JSON.stringify(token)}: ${why}. ` +
+            'Use <jailPort> (e.g. 3001) or <hostPort>:<jailPort> (e.g. 8080:3001), ' +
+            'each 1..65535.');
+    };
+    const parts = token.split(':');
+    if (parts.length > 2)
+        bad('too many colons');
+    const toPort = (s) => {
+        if (!/^[0-9]+$/.test(s))
+            bad(`${JSON.stringify(s)} is not a port number`);
+        const n = Number(s);
+        if (n < 1 || n > 65535)
+            bad(`${s} is out of range (1..65535)`);
+        return n;
+    };
+    if (parts.length === 1) {
+        const p = toPort(parts[0]);
+        return { hostPort: p, jailPort: p, raw: String(p) };
+    }
+    const hostPort = toPort(parts[0]);
+    const jailPort = toPort(parts[1]);
+    const raw = hostPort === jailPort ? String(jailPort) : `${hostPort}:${jailPort}`;
+    return { hostPort, jailPort, raw };
+}
+/**
+ * PURE: parse `anon-pi forward [<project>] [--port <[hostPort:]jailPort>]
+ * [--bind <addr>] [-m <machine>]`. The bare positional is ALWAYS the project (so
+ * a numeric name like `3001` is a project, never a port); the port is the
+ * `--port`/`-p` flag, removing the number-vs-project ambiguity. `--bind` is
+ * passed through to netcage (which validates 127.0.0.1 / 0.0.0.0). Throws
+ * AnonPiError on an unknown flag, a missing flag argument, a second positional,
+ * or a bad port.
+ */
+export function parseForwardArgs(args) {
+    const fail = (msg) => {
+        throw new AnonPiError(`anon-pi: ${msg}\nRun \`anon-pi forward --help\`.`);
+    };
+    let project;
+    let machine = DEFAULT_MACHINE;
+    let machineExplicit = false;
+    let port;
+    let bind;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-m' || a === '--machine') {
+            const v = args[++i];
+            if (v === undefined)
+                fail(`${a} needs a machine name`);
+            machine = validateName(v, 'machine');
+            machineExplicit = true;
+        }
+        else if (a === '-p' || a === '--port') {
+            const v = args[++i];
+            if (v === undefined)
+                fail(`${a} needs a port ([hostPort:]jailPort)`);
+            port = parsePortArg(v);
+        }
+        else if (a === '--bind') {
+            const v = args[++i];
+            if (v === undefined)
+                fail('--bind needs an address (127.0.0.1 or 0.0.0.0)');
+            bind = v;
+        }
+        else if (a.startsWith('-')) {
+            fail(`unknown option: ${a}`);
+        }
+        else if (project === undefined) {
+            project = validateName(a, 'project');
+        }
+        else {
+            fail(`unexpected argument: ${a} (forward takes at most one project)`);
+        }
+    }
+    return { project, machine, machineExplicit, port, bind };
+}
+/**
+ * PURE: parse `anon-pi ports [<project>] [-m <machine>]`. Like forward but with
+ * no port/bind: it lists a container's open in-jail listeners. The bare
+ * positional is the project filter.
+ */
+export function parsePortsArgs(args) {
+    const fail = (msg) => {
+        throw new AnonPiError(`anon-pi: ${msg}\nRun \`anon-pi ports --help\`.`);
+    };
+    let project;
+    let machine = DEFAULT_MACHINE;
+    let machineExplicit = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-m' || a === '--machine') {
+            const v = args[++i];
+            if (v === undefined)
+                fail(`${a} needs a machine name`);
+            machine = validateName(v, 'machine');
+            machineExplicit = true;
+        }
+        else if (a.startsWith('-')) {
+            fail(`unknown option: ${a}`);
+        }
+        else if (project === undefined) {
+            project = validateName(a, 'project');
+        }
+        else {
+            fail(`unexpected argument: ${a} (ports takes at most one project)`);
+        }
+    }
+    return { project, machine, machineExplicit };
+}
+/**
+ * PURE: parse `netcage ports --json` output into listeners (best-effort). Keeps
+ * only well-formed `{address:string, port:int, loopbackOnly:bool}` entries;
+ * anything else (a netcage version drift, a non-array) yields []. The caller
+ * treats [] as "no hint", never an error.
+ */
+export function parseNetcagePortsJson(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const e of parsed) {
+        if (!e || typeof e !== 'object')
+            continue;
+        const r = e;
+        if (typeof r.address === 'string' &&
+            typeof r.port === 'number' &&
+            typeof r.loopbackOnly === 'boolean') {
+            out.push({
+                address: r.address,
+                port: r.port,
+                loopbackOnly: r.loopbackOnly,
+            });
+        }
+    }
+    return out;
+}
+/** netcage's in-jail DNS forwarder always listens here; anon-pi hides it from the port hint. */
+export const NETCAGE_DNS_PORT = 53;
+/**
+ * PURE: the in-jail ports worth offering as forward targets: the listeners with
+ * netcage's own `127.0.0.1:53` DNS forwarder dropped (it is never something a
+ * user forwards), de-duplicated by port, sorted ascending. A server bound on
+ * both IPv4 and IPv6 (two listeners, same port) collapses to one entry.
+ */
+export function forwardablePorts(listeners) {
+    const ports = new Set();
+    for (const l of listeners) {
+        if (l.port === NETCAGE_DNS_PORT && l.loopbackOnly)
+            continue;
+        ports.add(l.port);
+    }
+    return [...ports].sort((a, b) => a - b);
+}
+/**
+ * PURE: a compact one-line hint of a container's forwardable in-jail ports for
+ * the picker / the pre-forward confirmation, e.g. `open: 3001, 5173` or
+ * `open: (none detected)`. Never includes the DNS forwarder (forwardablePorts).
+ */
+export function formatPortsHint(listeners) {
+    const ports = forwardablePorts(listeners);
+    return ports.length === 0
+        ? 'open: (none detected)'
+        : `open: ${ports.join(', ')}`;
+}
 // --- The bare-launch menu: choice-list + per-machine project-usage record ----
 //
 // anon-pi's bare launch shows a HOST-side arrow-key menu of a machine's
@@ -1831,12 +2201,14 @@ USAGE
   anon-pi                        MENU: pick a project (pi), a shell, or a new project
   anon-pi <project>              pi in the project (${CONTAINER_PROJECTS_ROOT}/<project>); exit pi -> host
   anon-pi <project> <pi-args…>   forward args to pi (e.g. -p for a headless one-shot)
-  anon-pi --session <id>         resume a pi session by id (forwarded to pi; no project needed)
-  anon-pi --continue             continue your most recent pi session (also -r/--resume, --fork)
+  anon-pi --session <id>         resume a pi session by id, in its own project (also -r/--resume)
+  anon-pi <project> --fork <id>  fork a session into <project> (\`.\`=root; --continue too; project required)
   anon-pi --list-models          list the models pi sees (also --models; no project needed)
   anon-pi pi <pi-args…>          run pi with ANY args and no project (the passthrough)
   anon-pi --version              print anon-pi's version (also -V)
   anon-pi --shell [<project>]    a jailed bash (at ~, or cd'd into <project>) - the project-hopper
+  anon-pi forward [<p>] [--port …]  open a host port onto a running container's in-jail server
+  anon-pi ports [<project>]      list a running container's open in-jail TCP listeners
   anon-pi -m <machine> [<p>]     the same, on <machine> (its own image + home + conversations)
   anon-pi --mount <parent> [<p>] root at a HOST parent folder instead of the projects root
   anon-pi init                   onboard: verify your proxy, capture your local model, pick an image