agent-sin 0.1.12 → 0.1.16

package/builtin-skills/even-g2-setup/main.ts

@@ -0,0 +1,896 @@
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { access, chmod, cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+type Locale = "en" | "ja";
+
+type SkillInput = {
+  args?: Record<string, unknown>;
+  sources?: {
+    workspace?: string;
+    locale?: string;
+  };
+};
+
+type SkillResult = {
+  status: "ok" | "error" | "skipped";
+  title: string;
+  summary: string;
+  outputs: Record<string, unknown>;
+  data: Record<string, unknown>;
+  suggestions: unknown[];
+};
+
+type HistoryChannel = "discord" | "telegram" | "none" | "auto";
+
+type ResolvedInputs = {
+  locale: Locale;
+  workspace: string;
+  envPath: string;
+  templateSrc: string;
+  templateDst: string;
+  packageId: string;
+  historyChannel: HistoryChannel;
+  discordThread: string | null;
+  host: string;
+  port: number;
+  token: string;
+  lanIp: string | null;
+  tailscaleHost: string | null;
+  serverUrl: string | null;
+  extraHosts: string[];
+  skipInstall: boolean;
+  skipPack: boolean;
+  force: boolean;
+};
+
+const GATEWAY_PORT_DEFAULT = 8765;
+const VITE_DEV_PORT = 5173;
+
+export async function run(_ctx: unknown, input: SkillInput): Promise<SkillResult> {
+  const locale: Locale = input.sources?.locale === "ja" ? "ja" : "en";
+  const args = (input.args || {}) as Record<string, unknown>;
+
+  let inputs: ResolvedInputs;
+  try {
+    inputs = resolveInputs(args, input.sources?.workspace, locale);
+  } catch (error) {
+    return errorResult(locale, "Setup failed", "セットアップに失敗しました", error, {});
+  }
+
+  const logs: string[] = [];
+  const warnings: string[] = [];
+
+  const tailscaleHostnames = collectTailscaleHostnames(inputs);
+  if (tailscaleHostnames.length > 0) {
+    const tailscaleCheck = checkTailscale(tailscaleHostnames);
+    if (!tailscaleCheck.ok) {
+      return errorResult(locale, "Tailscale not ready", "Tailscale が使えません", new Error(tailscaleCheck.message), {
+        hostnames: tailscaleHostnames,
+        hint: tailscaleCheck.hint,
+      });
+    }
+    logs.push(
+      locale === "ja"
+        ? `Tailscale OK（自分のホスト: ${tailscaleCheck.selfHost}）`
+        : `Tailscale OK (self: ${tailscaleCheck.selfHost})`,
+    );
+
+    if (inputs.serverUrl && /^https:/i.test(inputs.serverUrl)) {
+      const serveCheck = checkTailscaleServe(inputs.serverUrl, inputs.port);
+      if (!serveCheck.ok) {
+        return errorResult(locale, "Tailscale Serve not configured", "Tailscale Serve 未設定", new Error(serveCheck.message), {
+          server_url: inputs.serverUrl,
+          gateway_port: inputs.port,
+          hint: serveCheck.hint,
+        });
+      }
+      logs.push(
+        locale === "ja"
+          ? `Tailscale Serve OK（${serveCheck.matched}）`
+          : `Tailscale Serve OK (${serveCheck.matched})`,
+      );
+    }
+  }
+
+  try {
+    await mkdir(inputs.templateDst, { recursive: true });
+    const copyReport = await copyTemplate(inputs.templateSrc, inputs.templateDst, {
+      force: inputs.force,
+    });
+    logs.push(
+      locale === "ja"
+        ? `テンプレを ${inputs.templateDst} に配置（コピー: ${copyReport.copied}, スキップ: ${copyReport.skipped}）`
+        : `Prepared template at ${inputs.templateDst} (copied: ${copyReport.copied}, skipped: ${copyReport.skipped})`,
+    );
+
+    const extrasWithServer = inputs.serverUrl
+      ? [...inputs.extraHosts, inputs.serverUrl]
+      : inputs.extraHosts;
+    const whitelist = buildWhitelist({
+      lanIp: inputs.lanIp,
+      tailscaleHost: inputs.tailscaleHost,
+      extraHosts: extrasWithServer,
+      gatewayPort: inputs.port,
+      viteDevPort: VITE_DEV_PORT,
+    });
+    await writeAppJson(path.join(inputs.templateDst, "app.json"), inputs.templateSrc, whitelist, inputs.packageId);
+    logs.push(
+      locale === "ja"
+        ? `app.json を更新（package_id=${inputs.packageId}, whitelist ${whitelist.length} 件）`
+        : `Updated app.json (package_id=${inputs.packageId}, whitelist ${whitelist.length} entries)`,
+    );
+
+    const embeddedServer = pickEmbeddedServer(inputs);
+    await writeEmbeddedConfig(path.join(inputs.templateDst, "src", "embedded-config.ts"), embeddedServer, inputs.token);
+    logs.push(
+      locale === "ja"
+        ? `embedded-config.ts に server=${embeddedServer || "(なし)"} と token を埋め込み`
+        : `Embedded server=${embeddedServer || "(none)"} and token into embedded-config.ts`,
+    );
+
+    const dotenvEntries: Array<{ key: string; value: string }> = [
+      { key: "AGENT_SIN_G2_ENABLED", value: "1" },
+      { key: "AGENT_SIN_G2_HOST", value: inputs.host },
+      { key: "AGENT_SIN_G2_PORT", value: String(inputs.port) },
+      { key: "AGENT_SIN_G2_TOKEN", value: inputs.token },
+      { key: "AGENT_SIN_G2_HISTORY_CHANNEL", value: inputs.historyChannel },
+    ];
+    if (inputs.discordThread !== null) {
+      dotenvEntries.push({ key: "AGENT_SIN_G2_DISCORD_THREAD", value: inputs.discordThread });
+    }
+    await upsertDotenv(inputs.envPath, dotenvEntries);
+    logs.push(locale === "ja" ? `${inputs.envPath} に G2 設定を保存` : `Wrote G2 env to ${inputs.envPath}`);
+
+    let ehpkPath: string | null = null;
+    let partial = false;
+
+    const npmAvailable = await commandExists("npm");
+    if (!npmAvailable) {
+      partial = true;
+      warnings.push(
+        locale === "ja"
+          ? "npm が見つからないため install / pack をスキップしました。Node.js 22+ を入れ直してから再実行してください"
+          : "npm is not available; skipped install/pack. Install Node.js 22+ and re-run this skill.",
+      );
+    } else {
+      const nodeModulesExists = existsSync(path.join(inputs.templateDst, "node_modules"));
+      if (!inputs.skipInstall && (!nodeModulesExists || inputs.force)) {
+        const installResult = await runNpm(inputs.templateDst, ["install"]);
+        if (installResult.code !== 0) {
+          return errorResult(
+            locale,
+            "npm install failed",
+            "npm install に失敗しました",
+            new Error(installResult.stderr.trim() || installResult.stdout.trim() || `exit ${installResult.code}`),
+            { dotenv_path: inputs.envPath, template_dir: inputs.templateDst, install_log: tail(installResult.stderr, 2000) },
+          );
+        }
+        logs.push(locale === "ja" ? "npm install 完了" : "npm install completed");
+      } else {
+        logs.push(locale === "ja" ? "npm install はスキップ" : "Skipped npm install");
+      }
+
+      if (!inputs.skipPack) {
+        const packResult = await runNpm(inputs.templateDst, ["run", "pack"]);
+        const candidatePath = path.join(inputs.templateDst, "agent-sin-g2.ehpk");
+        if (packResult.code !== 0 || !existsSync(candidatePath)) {
+          const detail = packResult.stderr.trim() || packResult.stdout.trim() || `exit ${packResult.code}`;
+          return errorResult(
+            locale,
+            "npm run pack failed",
+            "npm run pack に失敗しました",
+            new Error(detail),
+            {
+              dotenv_path: inputs.envPath,
+              template_dir: inputs.templateDst,
+              pack_stdout: tail(packResult.stdout, 2000),
+              pack_stderr: tail(packResult.stderr, 2000),
+            },
+          );
+        }
+        ehpkPath = candidatePath;
+        logs.push(locale === "ja" ? `.ehpk を ${ehpkPath} に出力` : `Built ${ehpkPath}`);
+      } else {
+        logs.push(locale === "ja" ? "npm run pack はスキップ" : "Skipped npm run pack");
+      }
+    }
+
+    return okResult(locale, {
+      envPath: inputs.envPath,
+      templateDir: inputs.templateDst,
+      ehpkPath,
+      whitelist,
+      lanIp: inputs.lanIp,
+      historyChannel: inputs.historyChannel,
+      packageId: inputs.packageId,
+      partial,
+      warnings,
+      logs,
+    });
+  } catch (error) {
+    return errorResult(locale, "Setup failed", "セットアップに失敗しました", error, {
+      template_dir: inputs.templateDst,
+      env_path: inputs.envPath,
+    });
+  }
+}
+
+function resolveInputs(args: Record<string, unknown>, workspaceHint: string | undefined, locale: Locale): ResolvedInputs {
+  const workspace = workspaceHint || process.env.AGENT_SIN_HOME || path.join(os.homedir(), ".agent-sin");
+  const envPath = path.join(workspace, ".env");
+  const templateDst = path.join(workspace, "even-g2-agent");
+  const templateSrc = resolvePackageRoot();
+  const packageId = resolvePackageId(args.package_id, path.join(templateDst, "app.json"));
+
+  const historyChannel = normalizeHistoryChannel(args.history_channel) ?? "none";
+  const discordThread = normalizeDiscordThread(args.discord_thread);
+
+  const host = typeof args.host === "string" && args.host.trim() ? args.host.trim() : "0.0.0.0";
+  const port = typeof args.port === "number" && Number.isInteger(args.port) ? args.port : GATEWAY_PORT_DEFAULT;
+  const tokenInput = typeof args.token === "string" && args.token.trim().length >= 8 ? args.token.trim() : null;
+  const existingToken = process.env.AGENT_SIN_G2_TOKEN && process.env.AGENT_SIN_G2_TOKEN.trim();
+  const token = tokenInput || existingToken || randomBytes(16).toString("hex");
+
+  const lanIp = typeof args.host_lan_ip === "string" && args.host_lan_ip.trim()
+    ? args.host_lan_ip.trim()
+    : detectLanIp();
+  const tailscaleHost = typeof args.tailscale_host === "string" && args.tailscale_host.trim()
+    ? args.tailscale_host.trim()
+    : null;
+  const serverUrl = typeof args.server_url === "string" && args.server_url.trim()
+    ? args.server_url.trim().replace(/\/$/, "")
+    : null;
+  if (serverUrl && !/^https?:\/\//i.test(serverUrl)) {
+    throw new Error(`server_url must start with http:// or https:// (got: ${serverUrl})`);
+  }
+  const extraHosts = Array.isArray(args.extra_hosts)
+    ? (args.extra_hosts.filter((value): value is string => typeof value === "string" && value.trim().length > 0))
+    : [];
+
+  return {
+    locale,
+    workspace,
+    envPath,
+    templateSrc: path.join(templateSrc, "templates", "even-g2-agent"),
+    templateDst,
+    packageId,
+    historyChannel,
+    discordThread,
+    host,
+    port,
+    token,
+    lanIp,
+    tailscaleHost,
+    serverUrl,
+    extraHosts,
+    skipInstall: Boolean(args.skip_install),
+    skipPack: Boolean(args.skip_pack),
+    force: Boolean(args.force),
+  };
+}
+
+const PACKAGE_ID_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/;
+const FALLBACK_PACKAGE_ID = "com.example.agentsin";
+
+export function isValidPackageId(value: string): boolean {
+  return PACKAGE_ID_PATTERN.test(value);
+}
+
+export function sanitizeIdentifierSegment(value: string): string {
+  const stripped = value
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "");
+  return stripped.replace(/^[^a-z]+/, "");
+}
+
+function deriveFromGitUserName(): string | null {
+  try {
+    const result = spawnSync("git", ["config", "--global", "user.name"], { encoding: "utf8" });
+    if (result.status !== 0) return null;
+    const segment = sanitizeIdentifierSegment(result.stdout.trim());
+    if (!segment) return null;
+    return `com.${segment}.agentsin`;
+  } catch {
+    return null;
+  }
+}
+
+function readExistingPackageId(appJsonPath: string): string | null {
+  try {
+    if (!existsSync(appJsonPath)) return null;
+    const text = readFileSync(appJsonPath, "utf8");
+    const parsed = JSON.parse(text);
+    const value = typeof parsed?.package_id === "string" ? parsed.package_id.trim() : "";
+    return value && value !== FALLBACK_PACKAGE_ID ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolvePackageId(arg: unknown, existingAppJsonPath: string): string {
+  if (typeof arg === "string" && arg.trim()) {
+    const explicit = arg.trim();
+    if (!isValidPackageId(explicit)) {
+      throw new Error(
+        `Invalid package_id: "${explicit}". Use lowercase reverse-DNS (e.g. com.you.agentsin).`,
+      );
+    }
+    return explicit;
+  }
+  const existing = readExistingPackageId(existingAppJsonPath);
+  if (existing && isValidPackageId(existing)) return existing;
+  const derived = deriveFromGitUserName();
+  if (derived && isValidPackageId(derived)) return derived;
+  return FALLBACK_PACKAGE_ID;
+}
+
+function normalizeHistoryChannel(value: unknown): HistoryChannel | null {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "discord" || normalized === "telegram" || normalized === "none" || normalized === "auto") {
+    return normalized;
+  }
+  return null;
+}
+
+function normalizeDiscordThread(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^(auto|create|1|true|yes)$/i.test(trimmed)) return "auto";
+  if (/^(none|off|false|0)$/i.test(trimmed)) return "off";
+  if (/^\d+$/.test(trimmed)) return trimmed;
+  return null;
+}
+
+function resolvePackageRoot(): string {
+  const candidates: string[] = [];
+  const addAncestry = (start: string) => {
+    let current = path.resolve(start);
+    for (let depth = 0; depth < 6; depth += 1) {
+      candidates.push(current);
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  };
+  if (process.env.AGENT_SIN_PACKAGE_ROOT) candidates.push(process.env.AGENT_SIN_PACKAGE_ROOT);
+  const argv1 = process.argv[1];
+  if (argv1) {
+    addAncestry(path.dirname(argv1));
+    try {
+      const resolved = realpathSync(argv1);
+      addAncestry(path.dirname(resolved));
+    } catch {
+      // argv1 may not exist when running from REPL — fine
+    }
+  }
+  candidates.push(process.cwd());
+  for (const root of candidates) {
+    if (!root) continue;
+    if (existsSync(path.join(root, "templates", "even-g2-agent", "app.json"))) {
+      return root;
+    }
+  }
+  throw new Error(
+    "Could not locate the agent-sin package root with templates/even-g2-agent/. Set AGENT_SIN_PACKAGE_ROOT to override.",
+  );
+}
+
+export function detectLanIp(): string | null {
+  const interfaces = os.networkInterfaces();
+  for (const list of Object.values(interfaces)) {
+    if (!list) continue;
+    for (const info of list) {
+      if (info.family === "IPv4" && !info.internal) {
+        return info.address;
+      }
+    }
+  }
+  return null;
+}
+
+export function buildWhitelist(input: {
+  lanIp: string | null;
+  tailscaleHost: string | null;
+  extraHosts: string[];
+  gatewayPort: number;
+  viteDevPort: number;
+}): string[] {
+  const entries: string[] = [];
+  entries.push(`http://127.0.0.1:${input.gatewayPort}`);
+  entries.push(`http://127.0.0.1:${input.viteDevPort}`);
+  if (input.lanIp) {
+    entries.push(`http://${input.lanIp}:${input.gatewayPort}`);
+    entries.push(`http://${input.lanIp}:${input.viteDevPort}`);
+  }
+  if (input.tailscaleHost) {
+    entries.push(`http://${input.tailscaleHost}:${input.gatewayPort}`);
+  }
+  for (const raw of input.extraHosts) {
+    entries.push(normalizeWhitelistEntry(raw, input.gatewayPort));
+  }
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const entry of entries) {
+    const key = normalizeUrl(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(key);
+  }
+  return result;
+}
+
+export function normalizeWhitelistEntry(value: string, defaultPort: number): string {
+  const raw = value.trim();
+  if (!raw) return raw;
+  const hadScheme = /^https?:\/\//i.test(raw);
+  const withScheme = hadScheme ? raw : `http://${raw}`;
+  try {
+    const parsed = new URL(withScheme);
+    if (!hadScheme && !parsed.port) {
+      parsed.port = String(defaultPort);
+    }
+    return normalizeUrl(parsed.toString());
+  } catch {
+    return normalizeUrl(withScheme);
+  }
+}
+
+export function normalizeUrl(value: string): string {
+  try {
+    const url = new URL(value);
+    url.hostname = url.hostname.toLowerCase();
+    let out = url.toString();
+    if (out.endsWith("/") && !value.endsWith("/")) {
+      out = out.slice(0, -1);
+    }
+    return out;
+  } catch {
+    return value.trim();
+  }
+}
+
+function collectTailscaleHostnames(inputs: ResolvedInputs): string[] {
+  const hostnames: string[] = [];
+  if (inputs.tailscaleHost) hostnames.push(inputs.tailscaleHost);
+  if (inputs.serverUrl) {
+    try {
+      const { hostname } = new URL(inputs.serverUrl);
+      if (/\.ts\.net$/i.test(hostname)) hostnames.push(hostname);
+    } catch {
+      // ignore
+    }
+  }
+  return Array.from(new Set(hostnames.map((host) => host.toLowerCase())));
+}
+
+function checkTailscale(requestedHostnames: string[]): { ok: true; selfHost: string } | { ok: false; message: string; hint: string } {
+  const versionProbe = spawnSync("tailscale", ["--version"], { encoding: "utf8" });
+  if (versionProbe.error || versionProbe.status !== 0) {
+    return {
+      ok: false,
+      message: "tailscale CLI was not found. Install Tailscale (https://tailscale.com/download) and run `tailscale up` before re-running this skill.",
+      hint: "brew install --cask tailscale",
+    };
+  }
+  const statusProbe = spawnSync("tailscale", ["status", "--json"], { encoding: "utf8" });
+  if (statusProbe.error || statusProbe.status !== 0) {
+    return {
+      ok: false,
+      message: "tailscale status failed. Run `tailscale up` and sign in, then re-run this skill.",
+      hint: "tailscale up",
+    };
+  }
+  let parsed: any;
+  try {
+    parsed = JSON.parse(statusProbe.stdout);
+  } catch (error) {
+    return {
+      ok: false,
+      message: `Could not parse tailscale status: ${errorMessage(error)}`,
+      hint: "tailscale status --json",
+    };
+  }
+  if (parsed?.BackendState !== "Running") {
+    return {
+      ok: false,
+      message: `Tailscale is not running (state: ${parsed?.BackendState || "unknown"}). Run \`tailscale up\` and try again.`,
+      hint: "tailscale up",
+    };
+  }
+  const selfHost = String(parsed?.Self?.DNSName || "").replace(/\.$/, "").toLowerCase();
+  if (!selfHost) {
+    return {
+      ok: false,
+      message: "Could not determine this machine's Tailscale MagicDNS hostname.",
+      hint: "tailscale status --self",
+    };
+  }
+  for (const requested of requestedHostnames) {
+    if (requested.toLowerCase() !== selfHost) {
+      return {
+        ok: false,
+        message: `Tailscale hostname mismatch: requested "${requested}" but this machine is "${selfHost}". Use the matching host or update your input.`,
+        hint: `--tailscale-host ${selfHost}`,
+      };
+    }
+  }
+  return { ok: true, selfHost };
+}
+
+function checkTailscaleServe(serverUrl: string, gatewayPort: number): { ok: true; matched: string } | { ok: false; message: string; hint: string } {
+  const probe = spawnSync("tailscale", ["serve", "status", "--json"], { encoding: "utf8" });
+  if (probe.error || probe.status !== 0) {
+    return {
+      ok: false,
+      message: "Could not query Tailscale Serve status. Set it up so the gateway is reachable, then retry.",
+      hint: `tailscale serve --bg --https=443 / proxy http://localhost:${gatewayPort}`,
+    };
+  }
+  let parsed: any;
+  try {
+    parsed = JSON.parse(probe.stdout);
+  } catch (error) {
+    return {
+      ok: false,
+      message: `Could not parse tailscale serve status: ${errorMessage(error)}`,
+      hint: `tailscale serve --bg --https=443 / proxy http://localhost:${gatewayPort}`,
+    };
+  }
+  let url: URL;
+  try {
+    url = new URL(serverUrl);
+  } catch (error) {
+    return {
+      ok: false,
+      message: `Invalid server_url: ${errorMessage(error)}`,
+      hint: "Pass --server-url https://<your-tailnet>.ts.net",
+    };
+  }
+  const host = url.hostname.toLowerCase();
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  const targetPath = url.pathname && url.pathname !== "/" ? url.pathname : "/";
+  const web = parsed?.Web || {};
+  const entry = web[`${host}:${port}`];
+  if (!entry) {
+    return {
+      ok: false,
+      message: `Tailscale Serve has no handler for ${host}:${port}. Set one up so the gateway is reachable.`,
+      hint: `tailscale serve --bg --https=${port} / proxy http://localhost:${gatewayPort}`,
+    };
+  }
+  const handlers = entry.Handlers || {};
+  const matched = Object.entries(handlers).find(([handlerPath, conf]) => {
+    if (handlerPath !== targetPath) return false;
+    const proxy = String((conf as any)?.Proxy || "");
+    return proxy.includes(`localhost:${gatewayPort}`) || proxy.includes(`127.0.0.1:${gatewayPort}`);
+  });
+  if (!matched) {
+    const current = Object.entries(handlers).map(([path, conf]) => `${path} -> ${(conf as any)?.Proxy || "?"}`).join(", ") || "(none)";
+    return {
+      ok: false,
+      message: `Tailscale Serve does not proxy ${host}:${port}${targetPath} to localhost:${gatewayPort}. Current: ${current}.`,
+      hint: `tailscale serve --bg --https=${port} ${targetPath} proxy http://localhost:${gatewayPort}`,
+    };
+  }
+  return { ok: true, matched: `${host}:${port}${targetPath} → localhost:${gatewayPort}` };
+}
+
+function pickEmbeddedServer(inputs: ResolvedInputs): string {
+  if (inputs.serverUrl) return inputs.serverUrl;
+  if (inputs.tailscaleHost) return `http://${inputs.tailscaleHost}:${inputs.port}`;
+  if (inputs.lanIp) return `http://${inputs.lanIp}:${inputs.port}`;
+  return "";
+}
+
+async function writeEmbeddedConfig(targetPath: string, server: string, token: string): Promise<void> {
+  const escape = (value: string): string => value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+  const content = [
+    "// Auto-generated by the even-g2-setup skill at build time.",
+    "// Do not commit values from this file when sharing the template.",
+    `export const EMBEDDED_SERVER = "${escape(server)}";`,
+    `export const EMBEDDED_TOKEN = "${escape(token)}";`,
+    "",
+  ].join("\n");
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, content, "utf8");
+}
+
+async function writeAppJson(
+  targetPath: string,
+  templateDir: string,
+  whitelist: string[],
+  packageId: string,
+): Promise<void> {
+  let baseJson: Record<string, unknown> | null = null;
+  try {
+    const existing = await readFile(targetPath, "utf8");
+    baseJson = JSON.parse(existing) as Record<string, unknown>;
+  } catch {
+    baseJson = null;
+  }
+  if (!baseJson) {
+    try {
+      const text = await readFile(path.join(templateDir, "app.json"), "utf8");
+      baseJson = JSON.parse(text) as Record<string, unknown>;
+    } catch (error) {
+      throw new Error(`Failed to read template app.json: ${errorMessage(error)}`);
+    }
+  }
+  baseJson.package_id = packageId;
+  const permissions = Array.isArray(baseJson.permissions) ? [...(baseJson.permissions as unknown[])] : [];
+  if (permissions.length === 0) {
+    permissions.push({
+      name: "network",
+      desc: "Connects to the user's Agent-Sin gateway for private agent messages.",
+      whitelist: [],
+    });
+  }
+  const first = { ...(permissions[0] as Record<string, unknown>) };
+  first.whitelist = whitelist;
+  permissions[0] = first;
+  baseJson.permissions = permissions;
+  await writeFile(targetPath, `${JSON.stringify(baseJson, null, 2)}\n`, "utf8");
+}
+
+async function copyTemplate(
+  src: string,
+  dst: string,
+  options: { force: boolean },
+): Promise<{ copied: number; skipped: number }> {
+  const counters = { copied: 0, skipped: 0 };
+  try {
+    await access(src);
+  } catch {
+    throw new Error(`Template source not found: ${src}`);
+  }
+  await cp(src, dst, {
+    recursive: true,
+    force: options.force,
+    errorOnExist: false,
+    dereference: false,
+    filter: (source) => {
+      const rel = path.relative(src, source);
+      if (!rel) return true;
+      const first = rel.split(path.sep)[0];
+      if (first === "node_modules" || first === "dist" || first === ".git") {
+        counters.skipped += 1;
+        return false;
+      }
+      if (rel.endsWith(".ehpk")) {
+        counters.skipped += 1;
+        return false;
+      }
+      if (path.basename(rel) === "app.json") {
+        counters.skipped += 1;
+        return false;
+      }
+      counters.copied += 1;
+      return true;
+    },
+  });
+  return counters;
+}
+
+export function formatDotenvValue(value: string): string {
+  if (value === "") return "";
+  if (/^[A-Za-z0-9_./:@~+\-]+$/.test(value)) return value;
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+  return `"${escaped}"`;
+}
+
+export function upsertDotenvContent(existing: string, entries: Array<{ key: string; value: string }>): string {
+  const lines = existing.length > 0 ? existing.split(/\r?\n/) : [];
+  let trailingEmpty = false;
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+    trailingEmpty = true;
+  }
+  for (const entry of entries) {
+    const formatted = `${entry.key}=${formatDotenvValue(entry.value)}`;
+    const pattern = new RegExp(`^\\s*${entry.key.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}\\s*=.*$`);
+    const index = lines.findIndex((line) => pattern.test(line));
+    if (index >= 0) {
+      lines[index] = formatted;
+    } else {
+      lines.push(formatted);
+    }
+  }
+  return `${lines.join("\n")}${trailingEmpty || lines.length > 0 ? "\n" : ""}`;
+}
+
+async function upsertDotenv(envPath: string, entries: Array<{ key: string; value: string }>): Promise<void> {
+  let existing = "";
+  try {
+    existing = await readFile(envPath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  await mkdir(path.dirname(envPath), { recursive: true });
+  const next = upsertDotenvContent(existing, entries);
+  await writeFile(envPath, next, "utf8");
+  try {
+    await chmod(envPath, 0o600);
+  } catch {
+    // Permissions on Windows are best-effort; ignore.
+  }
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const probe = spawn(command, ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+    probe.once("error", () => resolve(false));
+    probe.once("exit", (code) => resolve(code === 0));
+  });
+}
+
+async function runNpm(cwd: string, args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+  return await new Promise((resolve, reject) => {
+    const child = spawn("npm", args, {
+      cwd,
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: process.platform === "win32",
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      resolve({ code: code ?? -1, stdout, stderr });
+    });
+  });
+}
+
+function tail(text: string, limit: number): string {
+  if (text.length <= limit) return text;
+  return `…${text.slice(text.length - limit)}`;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function okResult(
+  locale: Locale,
+  data: {
+    envPath: string;
+    templateDir: string;
+    ehpkPath: string | null;
+    whitelist: string[];
+    lanIp: string | null;
+    historyChannel: HistoryChannel;
+    packageId: string;
+    partial: boolean;
+    warnings: string[];
+    logs: string[];
+  },
+): SkillResult {
+  const summary = locale === "ja" ? buildSummaryJa(data) : buildSummaryEn(data);
+  return {
+    status: "ok",
+    title: locale === "ja" ? "Even G2 セットアップ完了" : "Even G2 setup completed",
+    summary,
+    outputs: {},
+    data: {
+      env_path: data.envPath,
+      template_dir: data.templateDir,
+      ehpk_path: data.ehpkPath,
+      whitelist: data.whitelist,
+      lan_ip: data.lanIp,
+      history_channel: data.historyChannel,
+      package_id: data.packageId,
+      partial: data.partial,
+      warnings: data.warnings,
+      logs: data.logs,
+    },
+    suggestions: [],
+  };
+}
+
+function errorResult(
+  locale: Locale,
+  titleEn: string,
+  titleJa: string,
+  error: unknown,
+  data: Record<string, unknown>,
+): SkillResult {
+  return {
+    status: "error",
+    title: locale === "ja" ? titleJa : titleEn,
+    summary: locale === "ja"
+      ? `セットアップ中にエラーが発生しました: ${errorMessage(error)}`
+      : `Setup failed: ${errorMessage(error)}`,
+    outputs: {},
+    data: { ...data, error: errorMessage(error) },
+    suggestions: [],
+  };
+}
+
+function buildSummaryJa(data: {
+  envPath: string;
+  templateDir: string;
+  ehpkPath: string | null;
+  whitelist: string[];
+  packageId: string;
+  partial: boolean;
+  warnings: string[];
+}): string {
+  const lines: string[] = [];
+  lines.push("Even G2 のセットアップが完了しました。");
+  lines.push("");
+  lines.push(`package_id: ${data.packageId}`);
+  lines.push(`.env: ${data.envPath}`);
+  lines.push(`テンプレ作業ディレクトリ: ${data.templateDir}`);
+  if (data.ehpkPath) {
+    lines.push(`.ehpk: ${data.ehpkPath}`);
+  }
+  lines.push("");
+  lines.push("次は人間操作:");
+  lines.push("  1. https://hub.evenrealities.com/ にサインインして My projects → Upload package で .ehpk をアップロード");
+  lines.push("  2. スマホの Even Realities アプリで Even Hub を開き、右上の Developer Hub（メガネアイコン）から Agent-Sin をインストール");
+  lines.push("");
+  lines.push("詳しい手順: docs/even-g2-setup.ja.md");
+  if (data.warnings.length > 0) {
+    lines.push("");
+    lines.push("注意:");
+    for (const warning of data.warnings) {
+      lines.push(`  - ${warning}`);
+    }
+  }
+  if (data.partial) {
+    lines.push("");
+    lines.push("一部の処理がスキップされたため、.ehpk の生成は完了していません。");
+  }
+  return lines.join("\n");
+}
+
+function buildSummaryEn(data: {
+  envPath: string;
+  templateDir: string;
+  ehpkPath: string | null;
+  whitelist: string[];
+  packageId: string;
+  partial: boolean;
+  warnings: string[];
+}): string {
+  const lines: string[] = [];
+  lines.push("Even G2 setup is complete.");
+  lines.push("");
+  lines.push(`package_id: ${data.packageId}`);
+  lines.push(`.env: ${data.envPath}`);
+  lines.push(`Template workspace: ${data.templateDir}`);
+  if (data.ehpkPath) {
+    lines.push(`.ehpk: ${data.ehpkPath}`);
+  }
+  lines.push("");
+  lines.push("Next, manual steps:");
+  lines.push("  1. Sign in to https://hub.evenrealities.com/, open My projects, and upload the .ehpk via Upload package.");
+  lines.push("  2. In the Even Realities phone app, open Even Hub, tap the Developer Hub (glasses icon) in the top-right, then install Agent-Sin.");
+  lines.push("");
+  lines.push("See docs/even-g2-setup.md for the full walkthrough.");
+  if (data.warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of data.warnings) {
+      lines.push(`  - ${warning}`);
+    }
+  }
+  if (data.partial) {
+    lines.push("");
+    lines.push("Some steps were skipped; the .ehpk was not built.");
+  }
+  return lines.join("\n");
+}