phasegate 0.144.0 → 0.145.0

package/scripts/harness/installation/domain/deployment-entry.ts

@@ -0,0 +1,86 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+import { Hash } from "./hash.js";
+import { ManagedBlock, type ManagedBlockInput } from "./managed-block.js";
+
+export type DeploymentEntryMode = "created" | "merged" | "symlink";
+
+export interface DeploymentEntryInput {
+  readonly path: string;
+  readonly mode: DeploymentEntryMode;
+  readonly block: ManagedBlock | ManagedBlockInput | null;
+  readonly hash: Hash | string;
+  readonly deployedAt: string;
+}
+
+export interface DeploymentEntryJson {
+  readonly path: string;
+  readonly mode: DeploymentEntryMode;
+  readonly block?: ManagedBlockInput | null;
+  readonly hash: string;
+  readonly deployedAt: string;
+}
+
+export class DeploymentEntry {
+  readonly path: string;
+  readonly mode: DeploymentEntryMode;
+  readonly block: ManagedBlock | null;
+  readonly hash: Hash;
+  readonly deployedAt: string;
+
+  private constructor(input: DeploymentEntryInput) {
+    if (input.path.trim().length === 0 || input.path.startsWith("/")) {
+      throw new Error("DeploymentEntry path must be a project-relative path");
+    }
+    if (!Number.isFinite(Date.parse(input.deployedAt))) {
+      throw new Error("DeploymentEntry deployedAt must be ISO8601-compatible");
+    }
+    const block = input.block instanceof ManagedBlock
+      ? input.block
+      : input.block === null
+        ? null
+        : ManagedBlock.create(input.block);
+    if (input.mode === "merged" && block === null) {
+      throw new Error("DeploymentEntry with mode merged requires a managed block");
+    }
+    if (input.mode !== "merged" && block !== null) {
+      throw new Error("DeploymentEntry block is only allowed for merged mode");
+    }
+    this.path = input.path;
+    this.mode = input.mode;
+    this.block = block;
+    this.hash = input.hash instanceof Hash ? input.hash : Hash.from(input.hash);
+    this.deployedAt = input.deployedAt;
+    Object.freeze(this);
+  }
+
+  static create(input: DeploymentEntryInput): DeploymentEntry {
+    return new DeploymentEntry(input);
+  }
+
+  static fromJSON(input: DeploymentEntryJson): DeploymentEntry {
+    return DeploymentEntry.create({
+      path: input.path,
+      mode: input.mode,
+      block: input.block ?? null,
+      hash: input.hash,
+      deployedAt: input.deployedAt,
+    });
+  }
+
+  equals(other: DeploymentEntry): boolean {
+    return this.path === other.path;
+  }
+
+  toJSON(): DeploymentEntryJson {
+    return {
+      path: this.path,
+      mode: this.mode,
+      block: this.block?.toJSON() ?? null,
+      hash: this.hash.toString(),
+      deployedAt: this.deployedAt,
+    };
+  }
+}

package/scripts/harness/installation/domain/deployment-manifest.ts

@@ -0,0 +1,90 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+import { DeploymentEntry, type DeploymentEntryJson } from "./deployment-entry.js";
+
+export interface DeploymentManifestInput {
+  readonly version: string;
+  readonly installedAt: string;
+  readonly entries: readonly DeploymentEntry[];
+}
+
+export interface DeploymentManifestJson {
+  readonly version: string;
+  readonly installedAt: string;
+  readonly entries: readonly DeploymentEntryJson[];
+}
+
+export class DeploymentManifest {
+  private static readonly SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+
+  readonly version: string;
+  readonly installedAt: string;
+  readonly entries: readonly DeploymentEntry[];
+
+  private constructor(input: DeploymentManifestInput) {
+    if (!DeploymentManifest.SEMVER_PATTERN.test(input.version)) {
+      throw new Error("DeploymentManifest version must be semver");
+    }
+    if (!Number.isFinite(Date.parse(input.installedAt))) {
+      throw new Error("DeploymentManifest installedAt must be ISO8601-compatible");
+    }
+    const paths = new Set<string>();
+    for (const entry of input.entries) {
+      if (paths.has(entry.path)) {
+        throw new Error(`DeploymentManifest contains duplicate entry path: ${entry.path}`);
+      }
+      paths.add(entry.path);
+    }
+    this.version = input.version;
+    this.installedAt = input.installedAt;
+    this.entries = Object.freeze([...input.entries]);
+    Object.freeze(this);
+  }
+
+  static create(version: string, installedAt = new Date().toISOString()): DeploymentManifest {
+    return new DeploymentManifest({ version, installedAt, entries: [] });
+  }
+
+  static reconstitute(input: DeploymentManifestInput): DeploymentManifest {
+    return new DeploymentManifest(input);
+  }
+
+  static fromJSON(input: DeploymentManifestJson): DeploymentManifest {
+    return DeploymentManifest.reconstitute({
+      version: input.version,
+      installedAt: input.installedAt,
+      entries: input.entries.map((entry) => DeploymentEntry.fromJSON(entry)),
+    });
+  }
+
+  addEntry(entry: DeploymentEntry): DeploymentManifest {
+    const entries = this.entries.filter((current) => current.path !== entry.path);
+    return DeploymentManifest.reconstitute({
+      version: this.version,
+      installedAt: this.installedAt,
+      entries: [...entries, entry],
+    });
+  }
+
+  removeEntry(path: string): DeploymentManifest {
+    return DeploymentManifest.reconstitute({
+      version: this.version,
+      installedAt: this.installedAt,
+      entries: this.entries.filter((entry) => entry.path !== path),
+    });
+  }
+
+  findEntry(path: string): DeploymentEntry | null {
+    return this.entries.find((entry) => entry.path === path) ?? null;
+  }
+
+  toJSON(): DeploymentManifestJson {
+    return {
+      version: this.version,
+      installedAt: this.installedAt,
+      entries: this.entries.map((entry) => entry.toJSON()),
+    };
+  }
+}

package/scripts/harness/installation/domain/diagnostic-finding.ts

@@ -0,0 +1,71 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+import type { CheckId } from "./check-id.js";
+import type { RepairMode } from "./repair-mode.js";
+import { SuggestedSkill, type SuggestedSkillInput } from "./suggested-skill.js";
+
+export type DiagnosticSeverity = "red" | "warn";
+
+export interface DiagnosticFindingInput {
+  readonly checkId: CheckId;
+  readonly severity: DiagnosticSeverity;
+  readonly target: string;
+  readonly message: string;
+  readonly repairMode: RepairMode;
+  readonly repairHint: string | null;
+  readonly suggestedSkill: SuggestedSkill | SuggestedSkillInput | null;
+}
+
+export interface DiagnosticFindingJson extends Omit<DiagnosticFindingInput, "suggestedSkill"> {
+  readonly suggestedSkill: SuggestedSkillInput | null;
+}
+
+export class DiagnosticFinding {
+  readonly checkId: CheckId;
+  readonly severity: DiagnosticSeverity;
+  readonly target: string;
+  readonly message: string;
+  readonly repairMode: RepairMode;
+  readonly repairHint: string | null;
+  readonly suggestedSkill: SuggestedSkill | null;
+
+  private constructor(input: DiagnosticFindingInput) {
+    const suggestedSkill = input.suggestedSkill instanceof SuggestedSkill
+      ? input.suggestedSkill
+      : input.suggestedSkill === null
+        ? null
+        : SuggestedSkill.create(input.suggestedSkill);
+    if (input.repairMode === "ai-assisted" && suggestedSkill === null) {
+      throw new Error("DiagnosticFinding requires suggestedSkill for ai-assisted repairMode");
+    }
+    if (input.target.trim().length === 0 || input.message.trim().length === 0) {
+      throw new Error("DiagnosticFinding target and message are required");
+    }
+    this.checkId = input.checkId;
+    this.severity = input.severity;
+    this.target = input.target;
+    this.message = input.message;
+    this.repairMode = input.repairMode;
+    this.repairHint = input.repairHint;
+    this.suggestedSkill = suggestedSkill;
+    Object.freeze(this);
+  }
+
+  static create(input: DiagnosticFindingInput): DiagnosticFinding {
+    return new DiagnosticFinding(input);
+  }
+
+  toJSON(): DiagnosticFindingJson {
+    return {
+      checkId: this.checkId,
+      severity: this.severity,
+      target: this.target,
+      message: this.message,
+      repairMode: this.repairMode,
+      repairHint: this.repairHint,
+      suggestedSkill: this.suggestedSkill?.toJSON() ?? null,
+    };
+  }
+}

package/scripts/harness/installation/domain/diagnostic-report.ts

@@ -0,0 +1,52 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+import { DiagnosticFinding } from "./diagnostic-finding.js";
+
+export type DiagnosticOverallStatus = "green" | "warn" | "red";
+
+export class DiagnosticReport {
+  readonly findings: readonly DiagnosticFinding[];
+  readonly overallStatus: DiagnosticOverallStatus;
+
+  private constructor(findings: readonly DiagnosticFinding[]) {
+    const checkIds = new Set<string>();
+    for (const finding of findings) {
+      if (checkIds.has(finding.checkId)) {
+        throw new Error(`DiagnosticReport contains duplicate checkId: ${finding.checkId}`);
+      }
+      checkIds.add(finding.checkId);
+    }
+    this.findings = Object.freeze([...findings]);
+    this.overallStatus = this.deriveStatus();
+    Object.freeze(this);
+  }
+
+  static create(findings: readonly DiagnosticFinding[]): DiagnosticReport {
+    return new DiagnosticReport(findings);
+  }
+
+  hasRedFlag(): boolean {
+    return this.findings.some((finding) => finding.severity === "red");
+  }
+
+  hasWarning(): boolean {
+    return this.findings.some((finding) => finding.severity === "warn" || finding.repairMode !== "mechanical");
+  }
+
+  toJSON() {
+    return {
+      overallStatus: this.overallStatus,
+      findings: this.findings.map((finding) => finding.toJSON()),
+    };
+  }
+
+  private deriveStatus(): DiagnosticOverallStatus {
+    if (this.findings.some((finding) => finding.severity === "red")) return "red";
+    if (this.findings.some((finding) => finding.severity === "warn" || finding.repairMode !== "mechanical")) {
+      return "warn";
+    }
+    return "green";
+  }
+}

package/scripts/harness/installation/domain/hash.ts

@@ -0,0 +1,30 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+export class Hash {
+  private static readonly PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+  readonly value: string;
+  readonly algorithm = "sha256";
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static from(value: string): Hash {
+    if (!Hash.PATTERN.test(value)) {
+      throw new Error("Hash must match sha256:<64 lowercase hex chars>");
+    }
+    return new Hash(value);
+  }
+
+  equals(other: Hash): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/installation/domain/managed-block.ts

@@ -0,0 +1,37 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+export interface ManagedBlockInput {
+  readonly start: string;
+  readonly end: string;
+  readonly content: string;
+}
+
+export class ManagedBlock {
+  readonly start: string;
+  readonly end: string;
+  readonly content: string;
+
+  private constructor(input: ManagedBlockInput) {
+    if (input.start.trim().length === 0 || input.end.trim().length === 0) {
+      throw new Error("ManagedBlock start and end markers are required");
+    }
+    this.start = input.start;
+    this.end = input.end;
+    this.content = input.content;
+    Object.freeze(this);
+  }
+
+  static create(input: ManagedBlockInput): ManagedBlock {
+    return new ManagedBlock(input);
+  }
+
+  toJSON(): ManagedBlockInput {
+    return {
+      start: this.start,
+      end: this.end,
+      content: this.content,
+    };
+  }
+}

package/scripts/harness/installation/domain/ports/heuristic-check.ts

@@ -0,0 +1,12 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../../application/ports/file-inspector-port.js";
+import type { CheckId } from "../check-id.js";
+import type { DiagnosticFinding } from "../diagnostic-finding.js";
+
+export interface HeuristicCheck {
+  readonly checkId: CheckId;
+  run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null>;
+}

package/scripts/harness/installation/domain/ports/merge-strategy.ts

@@ -0,0 +1,13 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+export interface MergeResult<T> {
+  readonly merged: T;
+  readonly changed: boolean;
+}
+
+export interface MergeStrategy<T> {
+  readonly fileType: "json" | "shell" | "yaml-add" | "package-json";
+  merge(existing: T | null, incoming: T): MergeResult<T>;
+}

package/scripts/harness/installation/domain/ports/reconcile-strategy.ts

@@ -0,0 +1,15 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+import type { DeploymentManifest } from "../deployment-manifest.js";
+
+export interface ReconcilePlan {
+  readonly operations: readonly string[];
+}
+
+export interface ReconcileStrategy {
+  readonly fromVersion: string;
+  readonly toVersion: string;
+  plan(currentManifest: DeploymentManifest): ReconcilePlan;
+}

package/scripts/harness/installation/domain/ports/uninstall-reverse-strategy.ts

@@ -0,0 +1,10 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+import type { ManagedBlock } from "../managed-block.js";
+
+export interface UninstallReverseStrategy {
+  readonly fileType: "json" | "shell" | "yaml-add" | "package-json";
+  reverse(currentContent: string, block: ManagedBlock): string;
+}

package/scripts/harness/installation/domain/repair-mode.ts

@@ -0,0 +1,11 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+export const REPAIR_MODES = ["mechanical", "ai-assisted", "manual"] as const;
+
+export type RepairMode = (typeof REPAIR_MODES)[number];
+
+export function isRepairMode(value: string): value is RepairMode {
+  return (REPAIR_MODES as readonly string[]).includes(value);
+}

package/scripts/harness/installation/domain/repair-table.ts

@@ -0,0 +1,41 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+import type { CheckId } from "./check-id.js";
+import { SuggestedSkill } from "./suggested-skill.js";
+
+const CONFIG_DOCTOR = SuggestedSkill.create({
+  skillName: "phasegate-config-doctor",
+  rationale: "既存設定にユーザーのカスタマイズがある場合、merge 位置と保持方針の判断が必要です。",
+  invokeCommand: "invoke /phasegate-config-doctor",
+});
+
+const TOOLKIT_GUIDE = SuggestedSkill.create({
+  skillName: "phasegate-toolkit-guide",
+  rationale: "既存 CI workflow との意味的な競合は人間の判断が必要です。",
+  invokeCommand: "invoke /phasegate-toolkit-guide",
+});
+
+export class RepairTable {
+  private readonly table: ReadonlyMap<CheckId, SuggestedSkill | null>;
+
+  constructor() {
+    this.table = new Map<CheckId, SuggestedSkill | null>([
+      ["claude-hook-missing", CONFIG_DOCTOR],
+      ["codex-hook-missing", CONFIG_DOCTOR],
+      ["husky-pre-commit-missing", CONFIG_DOCTOR],
+      ["husky-commit-msg-missing", CONFIG_DOCTOR],
+      ["husky-pre-push-missing", null],
+      ["ci-workflow-missing", TOOLKIT_GUIDE],
+      ["package-json-devdep-missing", null],
+      ["claude-skills-symlink", null],
+      ["codex-skills-symlink", null],
+    ]);
+    Object.freeze(this);
+  }
+
+  lookup(checkId: CheckId): SuggestedSkill | null {
+    return this.table.get(checkId) ?? null;
+  }
+}

package/scripts/harness/installation/domain/suggested-skill.ts

@@ -0,0 +1,37 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+export interface SuggestedSkillInput {
+  readonly skillName: string;
+  readonly rationale: string;
+  readonly invokeCommand: string;
+}
+
+export class SuggestedSkill {
+  readonly skillName: string;
+  readonly rationale: string;
+  readonly invokeCommand: string;
+
+  private constructor(input: SuggestedSkillInput) {
+    if (input.skillName.trim().length === 0 || input.invokeCommand.trim().length === 0) {
+      throw new Error("SuggestedSkill skillName and invokeCommand are required");
+    }
+    this.skillName = input.skillName;
+    this.rationale = input.rationale;
+    this.invokeCommand = input.invokeCommand;
+    Object.freeze(this);
+  }
+
+  static create(input: SuggestedSkillInput): SuggestedSkill {
+    return new SuggestedSkill(input);
+  }
+
+  toJSON(): SuggestedSkillInput {
+    return {
+      skillName: this.skillName,
+      rationale: this.rationale,
+      invokeCommand: this.invokeCommand,
+    };
+  }
+}

package/scripts/harness/installation/infrastructure/adapters/file-system-manifest-repository-adapter.ts

@@ -0,0 +1,62 @@
+// @unit installation
+// @layer infrastructure
+// @work-item-id WI-145
+
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, access } from "node:fs/promises";
+import { join } from "node:path";
+import { DeploymentManifest, type DeploymentManifestJson } from "../../domain/deployment-manifest.js";
+import type { ManifestRepositoryPort } from "../../application/ports/manifest-repository-port.js";
+
+export class ManifestParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ManifestParseError";
+  }
+}
+
+export class FileSystemManifestRepositoryAdapter implements ManifestRepositoryPort {
+  async load(projectRoot: string): Promise<DeploymentManifest | null> {
+    const manifestPath = this.manifestPath(projectRoot);
+    let raw: string;
+    try {
+      raw = await readFile(manifestPath, "utf8");
+    } catch {
+      return null;
+    }
+    try {
+      return DeploymentManifest.fromJSON(JSON.parse(raw) as DeploymentManifestJson);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ManifestParseError(`Failed to parse .phasegate/manifest.json: ${message}`);
+    }
+  }
+
+  async save(projectRoot: string, manifest: DeploymentManifest): Promise<void> {
+    const phasegateDir = join(projectRoot, ".phasegate");
+    await mkdir(phasegateDir, { recursive: true });
+    const tmpPath = join(phasegateDir, `${randomUUID()}.tmp`);
+    const manifestPath = this.manifestPath(projectRoot);
+    const content = `${JSON.stringify(manifest.toJSON(), null, 2)}\n`;
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(tmpPath, content, "utf8");
+    await rename(tmpPath, manifestPath);
+  }
+
+  async exists(projectRoot: string): Promise<boolean> {
+    try {
+      await access(this.manifestPath(projectRoot));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async archive(_projectRoot: string): Promise<void> {
+    throw new Error("Not yet implemented: manifest archive is owned by WI-147");
+  }
+
+  private manifestPath(projectRoot: string): string {
+    return join(projectRoot, ".phasegate", "manifest.json");
+  }
+}

package/scripts/harness/installation/infrastructure/adapters/node-crypto-hash-adapter.ts

@@ -0,0 +1,13 @@
+// @unit installation
+// @layer infrastructure
+// @work-item-id WI-145
+
+import { createHash } from "node:crypto";
+import { Hash } from "../../domain/hash.js";
+import type { HashCalculatorPort } from "../../application/ports/hash-calculator-port.js";
+
+export class NodeCryptoHashAdapter implements HashCalculatorPort {
+  compute(content: string | Buffer): Hash {
+    return Hash.from(`sha256:${createHash("sha256").update(content).digest("hex")}`);
+  }
+}

package/scripts/harness/installation/infrastructure/adapters/node-fs-file-inspector-adapter.ts

@@ -0,0 +1,53 @@
+// @unit installation
+// @layer infrastructure
+// @work-item-id WI-145
+
+import { lstat, readFile, readlink, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { FileInspectorPort } from "../../application/ports/file-inspector-port.js";
+
+export class NodeFsFileInspectorAdapter implements FileInspectorPort {
+  async exists(absolutePath: string): Promise<boolean> {
+    try {
+      await lstat(absolutePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async readText(absolutePath: string): Promise<string | null> {
+    try {
+      return await readFile(absolutePath, "utf8");
+    } catch {
+      return null;
+    }
+  }
+
+  async readJson<T = unknown>(absolutePath: string): Promise<T | null> {
+    try {
+      return JSON.parse(await readFile(absolutePath, "utf8")) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  async readSymlink(absolutePath: string): Promise<string | null> {
+    try {
+      const stats = await lstat(absolutePath);
+      if (!stats.isSymbolicLink()) return null;
+      return await readlink(absolutePath);
+    } catch {
+      return null;
+    }
+  }
+
+  async listFiles(absolutePath: string): Promise<string[]> {
+    try {
+      const entries = await readdir(absolutePath, { withFileTypes: true });
+      return entries.filter((entry) => entry.isFile()).map((entry) => join(absolutePath, entry.name));
+    } catch {
+      return [];
+    }
+  }
+}