phasegate 0.229.0 → 0.264.0

package/scripts/harness/world-model/presentation/cli/world-command-support.ts

@@ -0,0 +1,60 @@
+// @unit world-model
+// @layer presentation
+// @work-item-id WI-296
+
+export type WorldOutputFormat = "human" | "json";
+export interface WorldCommandResult {
+  readonly exitCode: 0 | 1 | 2;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export const parseFormat = (
+  args: readonly string[],
+):
+  | { readonly ok: true; readonly format: WorldOutputFormat; readonly rest: readonly string[] }
+  | {
+      readonly ok: false;
+      readonly format: WorldOutputFormat;
+      readonly message: string;
+    } => {
+  let format: WorldOutputFormat | undefined;
+  let json = false;
+  const rest: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--json") {
+      json = true;
+    } else if (argument === "--format") {
+      const value = args[index + 1];
+      if (value !== "human" && value !== "json") {
+        return { ok: false, format: json ? "json" : "human", message: "--format requires human or json" };
+      }
+      if (format !== undefined && format !== value) {
+        return { ok: false, format: json ? "json" : "human", message: "conflicting output format flags" };
+      }
+      format = value;
+      index += 1;
+    } else {
+      rest.push(argument);
+    }
+  }
+  if (json && format === "human") {
+    return { ok: false, format: "human", message: "conflicting output format flags" };
+  }
+  return { ok: true, format: json || format === "json" ? "json" : "human", rest };
+};
+
+export const envelope = (
+  command: "world:pin" | "world:derive",
+  exitCode: 0 | 1 | 2,
+  data: unknown,
+  diagnostics: readonly unknown[],
+) => ({
+  schemaVersion: "phasegate-world-cli/v1",
+  command,
+  ok: exitCode === 0,
+  exitCode,
+  data,
+  diagnostics,
+});

package/scripts/harness/world-model/presentation/cli/world-derive-command-handler.ts

@@ -0,0 +1,109 @@
+// @unit world-model
+// @layer presentation
+// @work-item-id WI-296
+// @work-item-id WI-300
+
+import type { DeriveWorldObligationsUseCase } from "../../application/usecases/derive-world-obligations-use-case.js";
+import { PathKey } from "../../domain/value-objects/path-key.js";
+import { envelope, parseFormat, type WorldCommandResult, type WorldOutputFormat } from "./world-command-support.js";
+
+export class WorldDeriveCommandHandler {
+  constructor(
+    private readonly useCase: Pick<DeriveWorldObligationsUseCase, "execute">,
+    private readonly defaultReportPath = ".harness/world-obligations.json",
+  ) {}
+
+  static fromFailure(error: unknown): WorldDeriveCommandHandler {
+    return new WorldDeriveCommandHandler({
+      execute: async () => {
+        throw error;
+      },
+    });
+  }
+
+  async execute(args: readonly string[]): Promise<WorldCommandResult> {
+    const formatted = parseFormat(args);
+    if (!formatted.ok) return this.failure(formatted.format, formatted.message);
+    let writeReport = false;
+    let reportPath: string | undefined;
+    for (let index = 0; index < formatted.rest.length; index += 1) {
+      const argument = formatted.rest[index];
+      if (argument === "--write") writeReport = true;
+      else if (argument === "--out") reportPath = formatted.rest[++index];
+      else return this.failure(formatted.format, `unknown argument: ${argument}`);
+    }
+    if (reportPath !== undefined && !writeReport) return this.failure(formatted.format, "--out requires --write");
+    if (reportPath !== undefined) {
+      try {
+        reportPath = PathKey.create(reportPath).toString();
+      } catch {
+        return this.failure(formatted.format, "--out must be a project-relative path");
+      }
+    }
+    try {
+      const result = await this.useCase.execute({ writeReport, reportPath });
+      if (result.status === "execution-failure") {
+        return this.executionFailure(formatted.format, result.diagnostics);
+      }
+      const report = result.result.report;
+      if (result.result.persistence.state === "failed") {
+        return this.executionFailure(formatted.format, [
+          { code: "report-write-failure", message: result.result.persistence.message },
+        ]);
+      }
+      const hasFinding =
+        report.structuralObligations.some(
+          (item) => item.classification === "new-structural" || item.classification === "invalid-declaration",
+        ) ||
+        report.repaidBaselineEntries.length > 0 ||
+        report.policyDiagnostics.length > 0;
+      const exitCode = hasFinding ? 1 : 0;
+      const data = {
+        report,
+        persistence: result.result.persistence,
+        writtenPath: writeReport ? (reportPath ?? this.defaultReportPath) : null,
+      };
+      if (formatted.format === "json") {
+        return {
+          exitCode,
+          stdout: `${JSON.stringify(envelope("world:derive", exitCode, data, report.policyDiagnostics))}\n`,
+          stderr: "",
+        };
+      }
+      return {
+        exitCode,
+        stdout: [
+          "World Obligations",
+          `  evaluationId: ${report.evaluationId}`,
+          `  structural: ${report.summary.structuralObligations}`,
+          `  repaid: ${report.summary.repaidBaselineEntries}`,
+          `  semantic debts: ${report.summary.declaredSemanticDebts}`,
+          `  policy diagnostics: ${report.summary.policyDiagnostics}`,
+          `  persistence: ${result.result.persistence.state}`,
+          ...(writeReport ? [`  writtenPath: ${data.writtenPath}`] : []),
+          "",
+        ].join("\n"),
+        stderr: "",
+      };
+    } catch (error) {
+      return this.failure(formatted.format, error instanceof Error ? error.message : String(error), true);
+    }
+  }
+
+  private executionFailure(format: WorldOutputFormat, diagnostics: readonly unknown[]): WorldCommandResult {
+    return format === "json"
+      ? { exitCode: 2, stdout: `${JSON.stringify(envelope("world:derive", 2, null, diagnostics))}\n`, stderr: "" }
+      : { exitCode: 2, stdout: "", stderr: `world:derive failed: ${JSON.stringify(diagnostics)}\n` };
+  }
+
+  private failure(format: WorldOutputFormat, message: string, execution = false): WorldCommandResult {
+    const code = execution ? "world-derive-execution-failure" : "invalid-invocation";
+    return format === "json"
+      ? {
+          exitCode: 2,
+          stdout: `${JSON.stringify(envelope("world:derive", 2, null, [{ code, message }]))}\n`,
+          stderr: "",
+        }
+      : { exitCode: 2, stdout: "", stderr: `world:derive ${execution ? "failed" : "usage error"}: ${message}\n` };
+  }
+}

package/scripts/harness/world-model/presentation/cli/world-inspect-command-handler.ts

@@ -0,0 +1,194 @@
+// @unit world-model
+// @layer presentation
+// @work-item-id WI-291
+
+import type {
+  WorldExtractionDiagnosticDto,
+  WorldInspectionDto,
+  WorldJsonObject,
+} from "../../application/dto/world-inspection-dto.js";
+import type { InspectWorldContract } from "../../application/usecases/inspect-world-use-case.js";
+
+export interface WorldInspectCommandResult {
+  readonly exitCode: 0 | 1 | 2;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface WorldInspectCommandHandlerDeps {
+  readonly inspectWorld: InspectWorldContract;
+}
+
+type OutputFormat = "human" | "json";
+
+interface ParsedFlags {
+  readonly ok: true;
+  readonly format: OutputFormat;
+}
+
+interface FlagFailure {
+  readonly ok: false;
+  readonly message: string;
+  readonly format: OutputFormat;
+}
+
+const executionDiagnostic = (message: string): WorldExtractionDiagnosticDto => ({
+  code: "world-inspect-execution-failure",
+  line: null,
+  nodeId: null,
+  pathKey: null,
+  payload: { message },
+});
+
+export class WorldInspectCommandHandler {
+  constructor(private readonly deps: WorldInspectCommandHandlerDeps) {}
+
+  static fromFailure(error: unknown): WorldInspectCommandHandler {
+    return new WorldInspectCommandHandler({
+      inspectWorld: {
+        execute: async () => {
+          throw error;
+        },
+      },
+    });
+  }
+
+  async execute(args: readonly string[]): Promise<WorldInspectCommandResult> {
+    const parsed = this.parseFlags(args);
+    if (!parsed.ok) return this.renderFailure(parsed.format, parsed.message, "invalid-invocation");
+    try {
+      const inspection = await this.deps.inspectWorld.execute();
+      const exitCode = inspection.summary.hardDiagnosticCount > 0 ? 1 : 0;
+      if (parsed.format === "json") {
+        return {
+          exitCode,
+          stdout: `${JSON.stringify(this.envelope(inspection, exitCode))}\n`,
+          stderr: "",
+        };
+      }
+      return {
+        exitCode,
+        stdout: this.renderHuman(inspection),
+        stderr: "",
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return this.renderFailure(parsed.format, message, "world-inspect-execution-failure");
+    }
+  }
+
+  private parseFlags(args: readonly string[]): ParsedFlags | FlagFailure {
+    let explicitFormat: OutputFormat | undefined;
+    let jsonAlias = false;
+    for (let index = 0; index < args.length; index += 1) {
+      const argument = args[index];
+      if (argument === "--json") {
+        jsonAlias = true;
+        continue;
+      }
+      if (argument === "--format") {
+        const value = args[index + 1];
+        if (value !== "human" && value !== "json") {
+          return {
+            ok: false,
+            message: "--format requires human or json",
+            format: jsonAlias ? "json" : "human",
+          };
+        }
+        if (explicitFormat !== undefined && explicitFormat !== value) {
+          return { ok: false, message: "conflicting output format flags", format: jsonAlias ? "json" : "human" };
+        }
+        explicitFormat = value;
+        index += 1;
+        continue;
+      }
+      return {
+        ok: false,
+        message: `unknown argument: ${argument}`,
+        format: jsonAlias || explicitFormat === "json" ? "json" : "human",
+      };
+    }
+    if (jsonAlias && explicitFormat === "human") {
+      return { ok: false, message: "conflicting output format flags", format: "human" };
+    }
+    return { ok: true, format: jsonAlias || explicitFormat === "json" ? "json" : "human" };
+  }
+
+  private envelope(
+    data: WorldInspectionDto | null,
+    exitCode: 0 | 1 | 2,
+    diagnostics?: readonly WorldExtractionDiagnosticDto[],
+  ): WorldJsonObject {
+    return {
+      schemaVersion: "phasegate-world-cli/v1",
+      command: "world:inspect",
+      ok: exitCode === 0,
+      exitCode,
+      data: data as unknown as WorldJsonObject | null,
+      diagnostics: diagnostics ?? data?.diagnostics ?? [],
+    };
+  }
+
+  private renderFailure(
+    format: OutputFormat,
+    message: string,
+    code: "invalid-invocation" | "world-inspect-execution-failure",
+  ): WorldInspectCommandResult {
+    if (format === "json") {
+      const diagnostic: WorldExtractionDiagnosticDto = {
+        ...executionDiagnostic(message),
+        code,
+      };
+      return {
+        exitCode: 2,
+        stdout: `${JSON.stringify(this.envelope(null, 2, [diagnostic]))}\n`,
+        stderr: "",
+      };
+    }
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr:
+        code === "invalid-invocation"
+          ? `world:inspect usage error: ${message}\n`
+          : `world:inspect failed: ${message}\n`,
+    };
+  }
+
+  private renderHuman(inspection: WorldInspectionDto): string {
+    const lines = [
+      "World Snapshot",
+      `  snapshotId: ${inspection.snapshotId}`,
+      `  corpusRoot: ${inspection.corpusRoot}`,
+      `  nodes: ${inspection.summary.nodeCount}`,
+      `  edges: ${inspection.summary.edgeCount}`,
+      `  diagnostics: ${inspection.summary.diagnosticCount} (hard: ${inspection.summary.hardDiagnosticCount})`,
+      "",
+      "Inventory",
+      `  nodeTypes: ${this.renderCounts(inspection.inventory.nodeTypes)}`,
+      `  corpusRoles: ${this.renderCounts(inspection.inventory.corpusRoles)}`,
+      `  artifactKinds: ${this.renderCounts(inspection.inventory.artifactKinds)}`,
+      "",
+      "Diagnostics",
+      ...(inspection.diagnostics.length === 0
+        ? ["  none"]
+        : inspection.diagnostics.map(
+            (diagnostic) =>
+              `  ${diagnostic.code} ${diagnostic.nodeId ?? diagnostic.pathKey ?? "<global>"}${
+                diagnostic.line === null ? "" : `:${diagnostic.line}`
+              }`,
+          )),
+      "",
+      "Next action",
+      inspection.summary.hardDiagnosticCount > 0
+        ? "  Resolve hard extraction diagnostics and rerun phasegate world:inspect."
+        : "  Snapshot is inspectable; no hard extraction diagnostics were found.",
+      "",
+    ];
+    return lines.join("\n");
+  }
+
+  private renderCounts(values: readonly { value: string; count: number }[]): string {
+    return values.length === 0 ? "none" : values.map((entry) => `${entry.value}=${entry.count}`).join(", ");
+  }
+}

package/scripts/harness/world-model/presentation/cli/world-pin-command-handler.ts

@@ -0,0 +1,100 @@
+// @unit world-model
+// @layer presentation
+// @work-item-id WI-296
+
+import type {
+  PinConstraintEndpointResult,
+  PinConstraintEndpointUseCase,
+  PinEndpointRole,
+} from "../../application/usecases/pin-constraint-endpoint-use-case.js";
+import { envelope, parseFormat, type WorldCommandResult, type WorldOutputFormat } from "./world-command-support.js";
+
+export class WorldPinCommandHandler {
+  constructor(private readonly useCase: Pick<PinConstraintEndpointUseCase, "execute">) {}
+
+  static fromFailure(error: unknown): WorldPinCommandHandler {
+    return new WorldPinCommandHandler({
+      execute: async () => {
+        throw error;
+      },
+    });
+  }
+
+  async execute(args: readonly string[]): Promise<WorldCommandResult> {
+    const formatted = parseFormat(args);
+    if (!formatted.ok) return this.failure(formatted.format, formatted.message);
+    let constraintId: string | undefined;
+    let endpoint: PinEndpointRole | undefined;
+    let apply = false;
+    for (let index = 0; index < formatted.rest.length; index += 1) {
+      const argument = formatted.rest[index];
+      if (argument === "--apply") apply = true;
+      else if (argument === "--constraint") constraintId = formatted.rest[++index];
+      else if (argument === "--endpoint") {
+        const value = formatted.rest[++index];
+        if (value !== "claimant" && value !== "premise")
+          return this.failure(formatted.format, "--endpoint requires claimant or premise");
+        endpoint = value;
+      } else return this.failure(formatted.format, `unknown argument: ${argument}`);
+    }
+    if (!constraintId || !/^pgw:v1:constraint:.+/.test(constraintId)) {
+      return this.failure(formatted.format, "--constraint requires a pgw:v1:constraint ID");
+    }
+    if (!endpoint) return this.failure(formatted.format, "--endpoint is required");
+    try {
+      const result = await this.useCase.execute({ constraintId, endpoint, apply });
+      return this.render(formatted.format, result);
+    } catch (error) {
+      return this.failure(formatted.format, error instanceof Error ? error.message : String(error), true);
+    }
+  }
+
+  private render(format: WorldOutputFormat, result: PinConstraintEndpointResult): WorldCommandResult {
+    const exitCode = result.status === "execution-failure" ? 2 : result.status === "domain-failure" ? 1 : 0;
+    const diagnostics =
+      result.status === "execution-failure"
+        ? result.diagnostics
+        : result.status === "domain-failure"
+          ? [{ code: result.code, message: result.message }]
+          : [];
+    if (format === "json") {
+      return {
+        exitCode,
+        stdout: `${JSON.stringify(envelope("world:pin", exitCode, result, diagnostics))}\n`,
+        stderr: "",
+      };
+    }
+    if (result.status === "execution-failure") {
+      return {
+        exitCode: 2,
+        stdout: "",
+        stderr: `world:pin failed: ${result.diagnostics[0]?.message ?? "execution failure"}\n`,
+      };
+    }
+    if (result.status === "domain-failure") {
+      return { exitCode: 1, stdout: `World Pin\n  status: ${result.code}\n  message: ${result.message}\n`, stderr: "" };
+    }
+    return {
+      exitCode: 0,
+      stdout: [
+        "World Pin",
+        `  status: ${result.status}`,
+        `  constraintId: ${result.candidate.constraintId}`,
+        `  endpoint: ${result.candidate.endpoint}`,
+        `  nodeId: ${result.candidate.nodeId}`,
+        `  before: ${result.candidate.beforeDigest}`,
+        `  after: ${result.candidate.afterDigest}`,
+        `  changed: ${result.candidate.changed}`,
+        "",
+      ].join("\n"),
+      stderr: "",
+    };
+  }
+
+  private failure(format: WorldOutputFormat, message: string, execution = false): WorldCommandResult {
+    const code = execution ? "world-pin-execution-failure" : "invalid-invocation";
+    return format === "json"
+      ? { exitCode: 2, stdout: `${JSON.stringify(envelope("world:pin", 2, null, [{ code, message }]))}\n`, stderr: "" }
+      : { exitCode: 2, stdout: "", stderr: `world:pin ${execution ? "failed" : "usage error"}: ${message}\n` };
+  }
+}