@trim21/personal-pi-extensions 0.0.206 → 0.0.209

package/README.md

@@ -222,7 +222,7 @@ session 间消息传递：不同 pi session（同一台机器）通过一个共
 
 ```
 storage.ts   —— 存储层：TalkStorage 接口 + SqliteTalkStorage 实现（node:sqlite，零 npm 依赖）
-core.ts      —— talk 核心：registry/mailbox/policy/format + TalkCore 协调器，只依赖存储层，通过回调 yield 投递/通知
+core.ts      —— talk 核心：registry/mailbox/group/policy/format + TalkCore 协调器，只依赖存储层，通过回调 yield 投递/通知
 index.ts     —— pi adapter：把 core 接到 pi 的 sendMessage / 生命周期事件 / 工具注册
 ```
 
@@ -230,18 +230,18 @@ index.ts     —— pi adapter：把 core 接到 pi 的 sendMessage / 生命周
 
 ### 工具（LLM 可见）
 
-| 工具                 | 作用                                                                                                                                                                                        |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `talk-list-sessions` | 列出会话，返回 JSON 数组（`status` / `work_dir` / `id` / `name`，自己带 `self: true`）；始终列出所有可见会话，`status` 区分 live（`idle` / `working` / `waiting-talk-message`）与 `offline` |
-| `talk-ask`           | 向某个 session 提问并阻塞等待回复（默认 30 分钟超时）                                                                                                                                       |
-| `talk-send`          | 发送纯文本消息到单个 session（`to` 只接受明确的 session id，不支持广播）                                                                                                                    |
-| `talk-reply`         | 回复一个 ask（`replyTo` 为 ask id，显式关联、不推断）                                                                                                                                       |
+| 工具                 | 作用                                                                                                                                                                                                      |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `talk-list-sessions` | 列出会话，返回 JSON 数组（`status` / `work_dir` / `id` / `name`，自己带 `self: true`）；只列出同组成员（未入组时只有自己），`status` 区分 live（`idle` / `working` / `waiting-talk-message`）与 `offline` |
+| `talk-ask`           | 向某个 session 提问并阻塞等待回复（默认 30 分钟超时）                                                                                                                                                     |
+| `talk-send`          | 发送纯文本消息到单个 session（`to` 只接受明确的 session id，不支持广播）                                                                                                                                  |
+| `talk-reply`         | 回复一个 ask（`replyTo` 为 ask id，显式关联、不推断）                                                                                                                                                     |
 
 对端消息自动投递（无需主动拉取）：投递方式由 `talk.deliver` 配置，`steer` 在模型工作过程中打断/唤醒，`queue` 排队到 session 下一轮自然 turn 时注入。
 
 **定位只认 session id**：`talk-send` / `talk-ask` / `talk-watch` 的 `to` 只接受 `talk-list-sessions` 返回的 `id`（pi 的 session uuid）精确匹配，不做 name/路径/前缀匹配。
 
-**标记废弃 session**：`/talk-dead` 给 session 打 `offline` 标志并把 `lastSeenAt` 置 0（列表显示为 offline，下次 sweep 无 mail 即回收）：无参标记当前 session，`/talk-dead <sessionId>` 标记指定 session，`/talk-dead --all` 标记所有其他可见 session。
+**标记废弃 session**：`/talk-dead` 给 session 打 `offline` 标志并把 `lastSeenAt` 置 0（列表显示为 offline，下次 sweep 无 mail 即回收）：无参标记当前 session，`/talk-dead <sessionId>` 标记指定 session，`/talk-dead --all` 标记所有其他可见 session（同组成员）。
 
 ### 关键设计
 
@@ -251,7 +251,7 @@ index.ts     —— pi adapter：把 core 接到 pi 的 sendMessage / 生命周
 - **双向 ask 仲裁**：`talk-ask` 发起前先检查收件箱（有对方消息就先读/先回）；阻塞等待期间若收到对方的 ask（而非 reply），按两个 ask 的 `ts` 字段仲裁——先 ask 者主导继续等，后 ask 者让位并先回复对方。`ts` 是信件内固定字段，双方读到同一对值，结论天然对称；同毫秒碰撞用 `session dir + session id` 字符串比较兜底。
 - **typebox runtime 验证**：所有从存储读出的值经 TypeBox schema 校验，损坏/伪造数据被拒绝，不做 `as T` 强转。
 - **安全**：纯文本 ≤32KB；10s 去重 / 30s 限速 8 条 / 50 积压上限（防环）；每条投递标注来源（来自另一个 pi session，非用户）。
-- **workspace 可见性**：每个 workspace 通过 `<cwd>/.pi/talk.json` 的 `allowed` 控制自己能看到哪些 session，见下方配置。
+- **group 可见性**：可见性完全由 group 决定——组内 session 只能看到同组成员，不在任何 group 的 session 只能看到自己。用 `/talk-group-*` 命令建组/入组，见下方「group 可见性」。
 
 ### 配置
 
@@ -277,22 +277,28 @@ sqlite 文件路径按优先级取第一个可用值：
 
 默认 `"queue"`。
 
-### workspace 可见性
+### group 可见性
 
-每个 workspace 通过 `<cwd>/.pi/talk.json` 的 `allowed` 决定自己能看到哪些 session：
+可见性完全由 group 决定，不再有路径/workspace 配置：
 
-```jsonc
-// ~/projects/company1/.pi/talk.json
-{
-  "allowed": ["~/projects/company1/"],
-}
+- 在某个 group 里的 session **只能看到同组成员**；不在任何 group 的 session **只能看到自己**。
+- group 是带 uuid 的私有房间：任何 session 都可以凭 uuid 加入任意 group，也可以自由离开，没有 owner。
+- 一个 session 只能属于一个 group：加入新 group 自动离开旧 group。
+- group 成员关系存在共享的 talk DB 里，每次 list/发送实时读取，加入/离开立即对所有 session 生效（无需重启）。
+
+通过 `/talk-group-*` 命令操作（TUI）：
+
+```
+/talk-group-join              # 无参：自动创建一个新 group（uuid 作为组名）并加入
+/talk-group-join <name>       # 加入名为 name 的 group；不存在则创建（名字允许字母/数字/-/_）
+/talk-group-join-last         # 加入最近创建的 group（方便新开 session 快速归队）
+/talk-group-leave             # 离开当前 group（组空了自动删除）
+/talk-group-list              # 列出所有 group 及其成员，最新创建的在前
+/talk-group-del <name>        # 删除指定 group（成员随之变为未入组）
+/talk-group-clear             # 删除所有 group
 ```
 
-- `allowed` 是路径前缀列表：能看到前缀本身及其子目录下的 session（`~/projects/company1/*`），看不到 `~/projects/company2/` 下的 session；`company1` 不会误匹配 `company12`
-- 路径支持 `~` 展开，相对路径相对该 workspace 的 cwd 解析
-- 无 `allowed` 字段 → 全部可见；`"allowed": []` → 谁都看不到
-- 可见性单向生效：A 的配置只决定 A 能看到谁，不影响 B
-- 不可见的 session 不仅 list 不到，也无法 `talk-send` / `talk-ask` 寻址（即使知道 id 也会被拒绝）
+典型用法：在 A session 里 `/talk-group-join`（或 `/talk-group-join mytask`）建组，把组名复制到 B、C session 里 `/talk-group-join <组名>`，此后 A/B/C 互相可见且只见彼此。
 
 | 变量              | 默认                              | 含义                            |
 | ----------------- | --------------------------------- | ------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.206",
+  "version": "0.0.209",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/gh-readonly.ts

@@ -31,7 +31,7 @@
 import { spawn } from "node:child_process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
@@ -603,12 +603,24 @@ export function cleanStepOutput(stepLog: string): string {
     .trim();
 }
 
+/**
+ * Strip terminal escape sequences and a leading UTF-8 BOM from a raw job log,
+ * keeping everything else — timestamps, `##[group]` markers, blank lines —
+ * intact. Used when writing a job's complete log to a file: complete, but
+ * readable without ANSI garbage.
+ */
+export function stripAnsi(text: string): string {
+  return text.replace(/^\uFEFF/, "").replaceAll(ANSI_RE, "");
+}
+
 export interface StepLogParams {
   runId: string;
   job?: string;
   step: string;
   offset?: number;
   limit?: number;
+  /** Return the complete, untruncated step output (ignores `offset`/`limit`). */
+  full?: boolean;
 }
 
 /**
@@ -623,7 +635,7 @@ export async function renderStepLog(
   fetchJobLog: (jobId: number) => Promise<string>,
   onUpdate?: (msg: CiLogsResult) => void,
 ): Promise<CiLogsResult> {
-  const { job, step, offset, limit } = params;
+  const { job, step, offset, limit, full } = params;
 
   if (!job) {
     return {
@@ -707,6 +719,26 @@ export async function renderStepLog(
 
   const clean = cleanStepOutput(stepLog);
 
+  // `full`: return the complete output, no truncation and no offset.
+  if (full) {
+    const fullLines = clean.split("\n").length;
+    return {
+      content: [{ type: "text", text: clean }],
+      details: {
+        summary: `Step ${stepNum} — ${targetJob.name} / ${found.name}: complete output (${fullLines} lines)`,
+        truncated: false,
+        full: true,
+        job: {
+          name: targetJob.name,
+          conclusion: targetJob.conclusion,
+          steps: stepsDetail(targetJob, new Set([stepNum])),
+        },
+        totalLines: fullLines,
+        shownLines: fullLines,
+      },
+    };
+  }
+
   // Apply offset on the cleaned text, then truncate.
   const totalLines = clean.split("\n").length;
   let logToShow = clean;
@@ -757,6 +789,8 @@ export interface JobLogsParams {
   job?: string;
   offset?: number;
   limit?: number;
+  /** Expand every step's complete output (default: only failed steps, truncated). */
+  full?: boolean;
 }
 
 export interface JobLogsStep {
@@ -781,7 +815,7 @@ export async function renderJobLogs(
   jobs: CiLogsJob[],
   fetchJobLog: (jobId: number) => Promise<string>,
 ): Promise<CiLogsResult> {
-  const { job, offset, limit } = params;
+  const { job, offset, limit, full } = params;
 
   if (!jobs || jobs.length === 0) {
     return {
@@ -814,7 +848,7 @@ export async function renderJobLogs(
     let rawLog: string | null = null;
 
     for (const s of j.steps) {
-      if (s.conclusion !== "failure") {
+      if (!full && s.conclusion !== "failure") {
         steps.push({ name: s.name });
         continue;
       }
@@ -828,6 +862,13 @@ export async function renderJobLogs(
         }
 
         const clean = cleanStepOutput(stepLog);
+
+        // `full`: every step carries its complete, untruncated output.
+        if (full) {
+          steps.push({ name: s.name, output: clean });
+          continue;
+        }
+
         const totalLines = clean.split("\n").length;
 
         // Apply offset on the cleaned text, then truncate.
@@ -856,7 +897,7 @@ export async function renderJobLogs(
 
   const totalJobs = output.length;
   const failedJobs = output.filter((j) => j.steps.some((s) => s.output !== undefined)).length;
-  const totalFailedSteps = output.reduce(
+  const expandedSteps = output.reduce(
     (acc, j) => acc + j.steps.filter((s) => s.output !== undefined).length,
     0,
   );
@@ -864,8 +905,11 @@ export async function renderJobLogs(
   return {
     content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
     details: {
-      summary: `${totalJobs} job${totalJobs > 1 ? "s" : ""}, ${failedJobs} failed, ${totalFailedSteps} failed step${totalFailedSteps > 1 ? "s" : ""}`,
+      summary: full
+        ? `${totalJobs} job${totalJobs > 1 ? "s" : ""}, ${expandedSteps} step output${expandedSteps === 1 ? "" : "s"} expanded (full, untruncated)`
+        : `${totalJobs} job${totalJobs > 1 ? "s" : ""}, ${failedJobs} failed, ${expandedSteps} failed step${expandedSteps > 1 ? "s" : ""}`,
       truncated: undefined,
+      ...(full && { full: true }),
       jobs: targetJobs.map((j) => ({
         name: j.name,
         conclusion: j.conclusion,
@@ -875,6 +919,142 @@ export async function renderJobLogs(
   };
 }
 
+// ── writing complete logs to a file ─────────────────────────────────────────
+
+export interface WriteLogFileParams {
+  runId: string;
+  job?: string;
+  step?: string;
+  outputFile: string;
+}
+
+/**
+ * Write the complete log to a file and return metadata (path, line/byte
+ * counts) instead of the log content itself. With `step`: the step's cleaned
+ * output. Without `step`: the whole job's log, timestamps and `##[group]`
+ * markers kept but ANSI escapes stripped. `job` is required when the run has
+ * more than one job (a single-job run is used implicitly). Relative
+ * `outputFile` paths resolve against `cwd`.
+ */
+export async function writeLogFile(
+  params: WriteLogFileParams,
+  jobs: CiLogsJob[],
+  fetchJobLog: (jobId: number) => Promise<string>,
+  cwd: string | undefined,
+  input: unknown,
+): Promise<CiLogsResult> {
+  const { job, step, outputFile } = params;
+
+  const isNumeric = /^\d+$/.test(job ?? "");
+  const targetJobs = job ? jobs.filter((j) => (isNumeric ? String(j.id) : j.name) === job) : jobs;
+  if (targetJobs.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Job "${job}" not found. Available: ${jobs.map((j) => `${j.name} (id: ${j.id})`).join(", ")}`,
+        },
+      ],
+      details: { input },
+    };
+  }
+  if (targetJobs.length > 1) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Job "${job}" matches ${targetJobs.length} jobs. Specify a unique job name or id. Available: ${jobs.map((j) => `${j.name} (id: ${j.id})`).join(", ")}`,
+        },
+      ],
+      details: { input },
+    };
+  }
+  const targetJob = targetJobs[0];
+
+  if (targetJob.status === "queued") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Job "${targetJob.name}" is still queued — no logs available yet. Use \`watch-github-run\` to wait for it to start, then retry.`,
+        },
+      ],
+      details: { input },
+    };
+  }
+
+  const rawLog = await fetchJobLog(targetJob.id);
+
+  let content: string;
+  let what: string;
+  if (step !== undefined && step !== null) {
+    const found = targetJob.steps.find((s) => s.name.toLowerCase() === step.toLowerCase());
+    if (!found) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Step "${step}" not found. Available: ${targetJob.steps.map((s) => `${s.name} (${s.number})`).join(", ")}`,
+          },
+        ],
+        details: { input },
+      };
+    }
+    const stepLog = extractStepFromLog(rawLog, found.number, targetJob.steps);
+    if (stepLog === null) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Could not extract step ${found.number} from job "${targetJob.name}" logs. The log may be malformed or empty.`,
+          },
+        ],
+        details: { input },
+      };
+    }
+    content = cleanStepOutput(stepLog);
+    what = `step ${found.number} ("${found.name}") of job "${targetJob.name}"`;
+  } else {
+    content = stripAnsi(rawLog);
+    what = `job "${targetJob.name}" (id: ${targetJob.id})`;
+  }
+
+  const target = resolve(cwd ?? process.cwd(), outputFile);
+  await mkdir(dirname(target), { recursive: true });
+  await withFileMutationQueue(target, async () => {
+    await writeFile(target, content);
+  });
+
+  const lines = content.split("\n").length;
+  const bytes = Buffer.byteLength(content, "utf8");
+
+  return {
+    content: [
+      {
+        type: "text",
+        text:
+          `## CI log written to \`${target}\`\n\n` +
+          `- content: ${what}\n` +
+          `- ${lines} lines, ${bytes} bytes\n` +
+          `- run: ${params.runId}\n\n` +
+          `Read it with the \`read\` tool (use \`offset\`/\`limit\` for large files).`,
+      },
+    ],
+    details: {
+      outputFile: target,
+      lines,
+      bytes,
+      runId: params.runId,
+      job: {
+        name: targetJob.name,
+        id: targetJob.id,
+        conclusion: targetJob.conclusion,
+      },
+      input,
+    },
+  };
+}
+
 // ── tools ────────────────────────────────────────────────────────────────────
 
 export default function ghReadonlyTools(pi: ExtensionAPI) {
@@ -1150,7 +1330,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     name: "read-github-ci-logs",
     label: "GitHub CI Logs",
     description:
-      "Get CI logs from a GitHub Actions workflow run. Without step: returns a JSON array of jobs [{name, steps:[{name, output?}]}] where every step is listed by name and failed steps carry their log as plain text in `output`. With step (requires job): returns that step's complete log as plain text. offset/limit control the size of every expanded output. Use run_id from list-github-workflow-runs. Note: queued jobs have no logs yet; use watch-github-run to wait for completion.",
+      "Get CI logs from a GitHub Actions workflow run. Without step: returns a JSON array of jobs [{name, steps:[{name, output?}]}] where every step is listed by name and failed steps carry their log as plain text in `output`. With step (requires job): returns that step's complete log as plain text. offset/limit control the size of every expanded output. Use run_id from list-github-workflow-runs. Note: queued jobs have no logs yet; use watch-github-run to wait for completion. Set full=true for complete untruncated outputs (every step when step is omitted; caution: very large outputs consume a lot of LLM context). Set output_file=/path to write the complete log to a file instead of returning it (requires job when the run has multiple jobs); the tool returns the file path to read.",
     promptSnippet: "Read GitHub CI logs",
     parameters: Type.Object({
       run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
@@ -1178,9 +1358,21 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
           description: "Maximum number of lines per output text (default 500).",
         }),
       ),
+      full: Type.Optional(
+        Type.Boolean({
+          description:
+            "Return complete, untruncated output instead of the default 500-line/60KB cap. With `step`: that step's full output. Without `step`: every step's full output (not just failed ones). Ignored when `output_file` is set. Caution: very large outputs consume a lot of LLM context — prefer `output_file` for big logs.",
+        }),
+      ),
+      output_file: Type.Optional(
+        Type.String({
+          description:
+            "Write the complete log to this file instead of returning it (relative paths resolve against the working directory). With `step` (requires `job`): the step's cleaned output. Without `step`: requires `job` (or a run with a single job) and writes that job's full log — timestamps and group markers kept, ANSI escapes stripped. Returns the file path; read it with the `read` tool.",
+        }),
+      ),
     }),
     async execute(_id, params, signal, onUpdate, ctx) {
-      const { run_id, repo, job, step, offset, limit } = params;
+      const { run_id, repo, job, step, offset, limit, full, output_file } = params;
 
       const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
       const jobsOut = await ghExec(["api", `/repos/${effectiveRepo}/actions/runs/${run_id}/jobs`], {
@@ -1193,6 +1385,17 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       const fetchJobLog = (jobId: number): Promise<string> =>
         getJobLog(String(run_id), jobId, effectiveRepo, signal, ctx.cwd, params);
 
+      // ── Write the complete log to a file ───────────────────────────────
+      if (output_file !== undefined && output_file !== null && output_file !== "") {
+        return writeLogFile(
+          { runId: String(run_id), job, step, outputFile: output_file },
+          jobs,
+          fetchJobLog,
+          ctx.cwd,
+          params,
+        );
+      }
+
       // ── Fetch a specific step's logs (requires `job`) ─────────────────
       if (step !== undefined && step !== null) {
         onUpdate?.({
@@ -1200,7 +1403,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
           details: {},
         });
         const stepResult = await renderStepLog(
-          { runId: String(run_id), job, step, offset, limit },
+          { runId: String(run_id), job, step, offset, limit, full },
           jobs,
           fetchJobLog,
           onUpdate,
@@ -1214,7 +1417,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
         details: {},
       });
       const jobsResult = await renderJobLogs(
-        { runId: String(run_id), job, offset, limit },
+        { runId: String(run_id), job, offset, limit, full },
         jobs,
         fetchJobLog,
       );

package/src/lib/cli-args.ts

@@ -0,0 +1,116 @@
+/**
+ * Minimal command-line argument parsing for `/command` handlers.
+ *
+ * The pi command API passes handlers a raw string (current versions) or a
+ * token array (newer ones); this helper accepts either and yields
+ * positionals plus flags, so handlers never care about the input shape.
+ *
+ * A raw string is split with shell-like rules first: whitespace separates
+ * tokens, single quotes preserve everything literally, double quotes allow
+ * `\"` / `\\` escapes, and a backslash outside quotes escapes the next
+ * character. Unlike bash, empty tokens are dropped and an unterminated
+ * quote raises a SyntaxError.
+ *
+ * Flags (only long form, `--name`):
+ *   --name value    flag "name" = "value" (value may not start with `--`)
+ *   --name=value    same
+ *   --flag          boolean flag = true
+ *   --              everything after is a positional
+ */
+
+export interface ParsedArgs {
+  /** Non-flag arguments, in order. */
+  positionals: string[];
+  /** `--name value` / `--name=value` → string; `--flag` → true. */
+  flags: Record<string, string | boolean>;
+}
+
+/** Does this token look like a long flag (`--x`, but not the bare `--`)? */
+function isFlagToken(token: string): boolean {
+  return token.startsWith("--") && token !== "--";
+}
+
+/** Shell-like tokenizer for a raw command line. Empty tokens are dropped. */
+export function shlexSplit(raw: string): string[] {
+  const tokens: string[] = [];
+  let cur = "";
+  let quote: "'" | '"' | undefined;
+  let i = 0;
+  while (i < raw.length) {
+    const c = raw[i];
+    if (quote) {
+      if (c === quote) {
+        quote = undefined;
+      } else if (c === "\\" && quote === '"' && (raw[i + 1] === '"' || raw[i + 1] === "\\")) {
+        cur += raw[i + 1];
+        i++;
+      } else {
+        cur += c;
+      }
+      i++;
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      quote = c;
+      i++;
+      continue;
+    }
+    if (c === "\\") {
+      if (i + 1 < raw.length) cur += raw[i + 1];
+      i += 2;
+      continue;
+    }
+    if (/\s/.test(c)) {
+      if (cur) {
+        tokens.push(cur);
+        cur = "";
+      }
+      i++;
+      continue;
+    }
+    cur += c;
+    i++;
+  }
+  if (quote !== undefined) {
+    throw new SyntaxError(`unterminated quote in command arguments: ${raw}`);
+  }
+  if (cur) tokens.push(cur);
+  return tokens;
+}
+
+export function parseArgs(input: string | string[]): ParsedArgs {
+  const tokens = Array.isArray(input) ? input : shlexSplit(input);
+  const positionals: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  let positionalOnly = false;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (positionalOnly) {
+      positionals.push(token);
+      continue;
+    }
+    if (token === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    const m = /^--([a-zA-Z0-9][a-zA-Z0-9-]*)(?:=(.*))?$/.exec(token);
+    if (!m) {
+      positionals.push(token);
+      continue;
+    }
+    const name = m[1];
+    if (m[2] !== undefined) {
+      flags[name] = m[2];
+      continue;
+    }
+    // `--name value` form: consume the next token unless it is itself a flag.
+    const next = tokens[i + 1];
+    if (next !== undefined && !isFlagToken(next)) {
+      flags[name] = next;
+      i++;
+    } else {
+      flags[name] = true;
+    }
+  }
+  return { positionals, flags };
+}