@akagilnc/pi-workflow-roles 0.1.2521 → 0.1.2653-next.71811ca

package/src/public-cli/notary-run.ts

@@ -1,68 +1,50 @@
 /**
- * Public Notary Role run: admit source-run locator → shared one-shot dispatch
- * → settle Terminal result (#448). Zero caller prompt/attachment. Lifecycle is
- * the shared Doctor-isomorphic seam; this module keeps only Notary adapters.
+ * Public Notary Role run: admit source-run locator → shared post-admission coordinator
+ * → settle Terminal result (#448 / #517). Zero caller prompt/attachment. Lifecycle is
+ * the shared post-admission seam; this module keeps only Notary adapters.
  */
+import type { DurablePrincipalAuthority, RoleTurnRequest } from "../host-contracts.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import {
   admitNotaryInvocation,
   buildNotaryTransportPrompt,
   type AdmittedNotaryInvocation,
-  type ParseNotaryArgvResult,
+  type ParseNotaryArgvResult
 } from "./invocation.ts";
 import {
-  buildSeatModelCliArgs,
-  type SeatModelConfig,
-} from "./config.ts";
-import {
-  runAdmittedOneShotRole,
-  type OneShotRunEnv,
-} from "./one-shot-dispatch.ts";
+  runPostAdmissionOneShot,
+  type PostAdmissionEnv,
+} from "./post-admission.ts";
+import { markRunAdmitted } from "./run-lifecycle.ts";
 import {
   presentStructuralRejection,
   trySettleNotaryTerminalResult,
 } from "./settlement.ts";
 import type { CliIo } from "./cli-io.ts";
 import type { TerminalResult } from "./terminal.ts";
+import {
+  projectRoleTurnRequest,
+  type RoleTurnRequestProjectionOptions,
+} from "./turn-request.ts";
 
-export type NotaryRunEnv = OneShotRunEnv & {
+export type NotaryRunEnv = PostAdmissionEnv & {
+  principalAuthority: DurablePrincipalAuthority;
   createRunId?: () => string;
-  extraPiArgs?: readonly string[];
 };
 
-export function buildNotaryActivationExtraArgs(
+/** Project admitted invocation onto the host-neutral turn request. */
+export function buildNotaryTurnRequest(
   admitted: AdmittedNotaryInvocation,
-  options: {
-    model?: SeatModelConfig;
-    engine?: string;
-    packageRoot?: string;
-    extraPiArgs?: readonly string[];
-  } = {},
-): string[] {
-  const prompt = buildNotaryTransportPrompt(
+  options: RoleTurnRequestProjectionOptions,
+): RoleTurnRequest {
+  return projectRoleTurnRequest(
     admitted,
-    engineSessionMaterialFromOptions(options),
+    {
+      activation: { role: "notary" as const, sourceRun: admitted.sourceRunPath },
+    },
+    options,
   );
-  return [
-    "--no-skills",
-    "--no-prompt-templates",
-    "--no-themes",
-    "--no-context-files",
-    "--session",
-    admitted.sessionFile,
-    "--session-dir",
-    admitted.sessionDirectory,
-    ...(options.extraPiArgs ?? []),
-    "--ak-role",
-    "notary",
-    "--ak-notary-source-run",
-    admitted.sourceRunPath,
-    "--mode",
-    "json",
-    ...buildSeatModelCliArgs(options.model),
-    prompt,
-  ];
 }
 
 export async function runPublicNotary(
@@ -80,6 +62,7 @@ export async function runPublicNotary(
     const parsed = parseNotaryArgv(argv);
     admitted = await admitNotaryInvocation({
       home: env.home,
+      principalAuthority: env.principalAuthority,
       cwd: env.cwd,
       sourceRun: parsed.sourceRun,
       ...(parsed.project === undefined ? {} : { project: parsed.project }),
@@ -95,20 +78,31 @@ export async function runPublicNotary(
     throw error;
   }
 
-  const extraArgs = buildNotaryActivationExtraArgs(admitted, {
+  await markRunAdmitted(admitted, env.principalAuthority);
+
+  const turnRequest = buildNotaryTurnRequest(admitted, {
     packageRoot: env.packageRoot,
+    home: env.home,
+    agentDir: env.agentDir,
     ...(env.model === undefined ? {} : { model: env.model }),
     ...(env.engine === undefined ? {} : { engine: env.engine }),
-    ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+    ...(env.correlationId === undefined || env.correlationId.trim() === ""
+      ? {}
+      : { correlationId: env.correlationId }),
+    continuation: {
+      kind: "initial",
+      prompt: buildNotaryTransportPrompt(admitted, engineSessionMaterialFromOptions({ ...(env.engine === undefined ? {} : { engine: env.engine }), packageRoot: env.packageRoot })),
+    },
   });
 
-  return await runAdmittedOneShotRole({
+  return await runPostAdmissionOneShot({
     admitted,
     env,
     io,
-    extraArgs,
+    request: turnRequest,
     adapters: {
-      trySettle: trySettleNotaryTerminalResult,
+      trySettle: (admitted, authority) => trySettleNotaryTerminalResult(admitted, authority),
       // Accepted receipts and failure terminals both present via shared path.
       shouldPresentSettled: () => true,
     },

package/src/public-cli/option-definitions.ts

@@ -2,8 +2,8 @@
  * #342 — sole typed public CLI option-definition source.
  *
  * PUBLIC_ROLE_ARGV rows reference these definitions. Production parsers and
- * `help <command>` consume this table. Do not maintain a parallel spelling set
- * in parsers, help, or docs.
+ * `help <command>` consume this table; README flag inventory is generated from
+ * it. Do not maintain a parallel spelling set in parsers, help, or docs.
  *
  * Dashed-option take, positional selector match, role-phase resolution,
  * `repeatable` enforcement, and unconditional `required` checks share one
@@ -215,7 +215,7 @@ export function evaluateAnalystModeOptionContract(
 
 /**
  * Rejected / internal spellings retained by parsers for explicit refusal.
- * Must never appear in public help.
+ * Must never appear in public help or README projections.
  */
 export type RejectedSpelling = {
   readonly owner: OptionOwner;
@@ -1219,3 +1219,136 @@ export function renderHumanOwnerOptionLines(
   }
   return lines;
 }
+
+const README_BEGIN = "<!-- BEGIN GENERATED: public-cli-options -->";
+const README_END = "<!-- END GENERATED: public-cli-options -->";
+
+export const PUBLIC_CLI_OPTIONS_README_MARKERS = {
+  begin: README_BEGIN,
+  end: README_END,
+} as const;
+
+/** Escape `|` so GFM table cells keep their column count (including inside code spans). */
+function escapeMarkdownTableCell(value: string): string {
+  return value.replaceAll("|", "\\|");
+}
+
+/** Markdown flag inventory for README generation (EN or ZH). */
+export function renderReadmeOptionsMarkdown(locale: "en" | "zh"): string {
+  const lines: string[] = [];
+  if (locale === "zh") {
+    lines.push("## 公开 CLI 选项（生成）");
+    lines.push("");
+    lines.push(
+      "本表由 `src/public-cli/option-definitions.ts` 生成；以 `ak-role help <command>` 为准。勿手改本区。",
+    );
+  } else {
+    lines.push("## Public CLI options (generated)");
+    lines.push("");
+    lines.push(
+      "Generated from `src/public-cli/option-definitions.ts`. Prefer `ak-role help <command>`. Do not hand-edit this section.",
+    );
+  }
+  lines.push("");
+
+  const owners: OptionOwner[] = ["global", ...PUBLIC_ROLE_OPTION_OWNERS];
+  for (const owner of owners) {
+    lines.push(locale === "zh" ? `### \`${owner}\`` : `### \`${owner}\``);
+    lines.push("");
+    lines.push(
+      locale === "zh"
+        ? "| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |"
+        : "| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |",
+    );
+    lines.push("| --- | --- | --- | --- | --- | --- | --- | --- |");
+    for (const opt of projectOwnerOptions(owner)) {
+      const aliasesRaw =
+        opt.aliases.length === 0 ? "—" : opt.aliases.join(", ");
+      const aliases =
+        aliasesRaw === "—"
+          ? aliasesRaw
+          : aliasesRaw
+              .split(", ")
+              .map((a) => `\`${escapeMarkdownTableCell(a)}\``)
+              .join(", ");
+      const valueRaw = opt.valueMetavar ?? "—";
+      const value =
+        valueRaw === "—"
+          ? valueRaw
+          : `\`${escapeMarkdownTableCell(valueRaw)}\``;
+      const requiredRaw = opt.required
+        ? locale === "zh"
+          ? "是"
+          : "yes"
+        : opt.requiredInModes !== undefined
+          ? locale === "zh"
+            ? `条件:${opt.requiredInModes.join("|")}`
+            : `when:${opt.requiredInModes.join("|")}`
+          : locale === "zh"
+            ? "否"
+            : "no";
+      const required = escapeMarkdownTableCell(requiredRaw);
+      const repeatable = escapeMarkdownTableCell(
+        opt.repeatable
+          ? locale === "zh"
+            ? "是"
+            : "yes"
+          : locale === "zh"
+            ? "否"
+            : "no",
+      );
+      const modePhase = escapeMarkdownTableCell(
+        [
+          opt.modes === undefined ? "" : `modes=${opt.modes.join("|")}`,
+          opt.phases === undefined ? "" : `phases=${opt.phases.join("|")}`,
+          opt.exclusiveWith === undefined
+            ? ""
+            : `xor=${opt.exclusiveWith.join("|")}`,
+          opt.maxCountByMode === undefined
+            ? ""
+            : `max=${Object.entries(opt.maxCountByMode)
+                .map(([m, n]) => `${m}:${n}`)
+                .join(",")}`,
+          opt.defaultValue === undefined ? "" : `default=${opt.defaultValue}`,
+        ]
+          .filter((part) => part !== "")
+          .join("; ") || "—",
+      );
+      const desc = escapeMarkdownTableCell(
+        locale === "zh" ? opt.description.zh : opt.description.en,
+      );
+      const spelling = `\`${escapeMarkdownTableCell(opt.canonical)}\``;
+      const form = escapeMarkdownTableCell(opt.form);
+      lines.push(
+        `| ${spelling} | ${aliases} | ${value} | ${required} | ${repeatable} | ${form} | ${modePhase} | ${desc} |`,
+      );
+    }
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+/**
+ * Replace the generated region inside a README body, or append one.
+ * Returns the full file text.
+ */
+export function applyReadmeOptionsSection(
+  readmeText: string,
+  locale: "en" | "zh",
+): string {
+  const section = `${README_BEGIN}\n${renderReadmeOptionsMarkdown(locale)}${README_END}\n`;
+  const beginIdx = readmeText.indexOf(README_BEGIN);
+  const endIdx = readmeText.indexOf(README_END);
+  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    const afterEnd = endIdx + README_END.length;
+    // Consume a single trailing newline after the end marker when present.
+    const tailStart =
+      readmeText[afterEnd] === "\n" ? afterEnd + 1 : afterEnd;
+    return (
+      readmeText.slice(0, beginIdx) + section + readmeText.slice(tailStart)
+    );
+  }
+  // No markers yet — append before EOF.
+  const base = readmeText.endsWith("\n") ? readmeText : `${readmeText}\n`;
+  return `${base}\n${section}`;
+}