skillwiki 0.9.63 → 0.10.1

package/dist/chunk-R6BKJWVC.js

@@ -0,0 +1,890 @@
+#!/usr/bin/env node
+import {
+  ExitCode,
+  FleetManifestSchema,
+  err,
+  ok
+} from "./chunk-C5OLZRRM.js";
+
+// src/utils/dotenv.ts
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+var CONFIG_KEYS = [
+  "WIKI_PATH",
+  "WIKI_LANG",
+  "SKILLWIKI_HOST_ID",
+  "AUTO_COMMIT",
+  "BACKUP_ENDPOINT",
+  "BACKUP_BUCKET",
+  "BACKUP_REGION",
+  "BACKUP_ACCESS_KEY_ID",
+  "BACKUP_SECRET_ACCESS_KEY"
+];
+var _whitelist = new Set(CONFIG_KEYS);
+var PROFILE_PATH_RE = /^WIKI_([A-Z][A-Z0-9_]{0,31})_PATH$/;
+var PROFILE_LANG_RE = /^WIKI_([A-Z][A-Z0-9_]{0,31})_LANG$/;
+var PROFILE_DEFAULT_RE = /^WIKI_DEFAULT$/;
+function isValidWikiProfileKey(key) {
+  if (key === "WIKI_PATH" || key === "WIKI_LANG") return false;
+  return PROFILE_PATH_RE.test(key) || PROFILE_LANG_RE.test(key) || PROFILE_DEFAULT_RE.test(key);
+}
+function profileKey(name, suffix) {
+  return `WIKI_${name.toUpperCase().replace(/-/g, "_").replace(/[^A-Z0-9_]/g, "")}_${suffix}`;
+}
+function parseDotenvText(text) {
+  const out = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    if (!_whitelist.has(key) && !isValidWikiProfileKey(key)) continue;
+    if (value.length === 0) continue;
+    out[key] = value;
+  }
+  return out;
+}
+async function parseDotenvFile(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return {};
+  }
+  return parseDotenvText(text);
+}
+async function writeDotenv(filePath, entries, originalContent) {
+  const lines = originalContent !== void 0 ? updateLines(originalContent, entries) : freshLines(entries);
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, lines.join("\n") + "\n", "utf8");
+}
+function freshLines(entries) {
+  const out = [];
+  for (const [key, value] of Object.entries(entries)) {
+    if (value !== void 0) out.push(`${key}=${value}`);
+  }
+  return out;
+}
+function updateLines(originalContent, entries) {
+  let rawLines = originalContent.split(/\r?\n/);
+  if (rawLines.length > 0 && rawLines[rawLines.length - 1] === "") {
+    rawLines = rawLines.slice(0, -1);
+  }
+  const keysToWrite = new Set(Object.keys(entries));
+  const out = [];
+  for (const line of rawLines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) {
+      out.push(line);
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      out.push(line);
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    if (keysToWrite.has(key)) {
+      out.push(`${key}=${entries[key]}`);
+      keysToWrite.delete(key);
+    } else {
+      out.push(line);
+    }
+  }
+  for (const key of keysToWrite) {
+    const value = entries[key];
+    if (value !== void 0) out.push(`${key}=${value}`);
+  }
+  return out;
+}
+
+// src/commands/fleet.ts
+import { readFile as readFile2 } from "fs/promises";
+import { hostname as nodeHostname, userInfo } from "os";
+import { join } from "path";
+import yaml from "js-yaml";
+var FLEET_REL_PATH = join("projects", "llm-wiki", "architecture", "fleet.yaml");
+async function runFleetValidate(input) {
+  const loaded = await loadFleetManifest(input.file);
+  if (!loaded.ok) {
+    if (loaded.error === "FILE_NOT_FOUND") {
+      return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: input.file }) };
+    }
+    const errors = fleetLoadErrors(loaded);
+    return invalidFleet(errors);
+  }
+  const warnings = fleetWarnings(loaded.manifest);
+  const snapshotter = findSnapshotter(loaded.manifest);
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      valid: true,
+      errors: [],
+      warnings,
+      host_count: Object.keys(loaded.manifest.hosts).length,
+      snapshotter,
+      humanHint: `VALID fleet manifest (${Object.keys(loaded.manifest.hosts).length} hosts; snapshotter: ${snapshotter ?? "none"})`
+    })
+  };
+}
+async function runFleetContext(input) {
+  const env = input.env ?? process.env;
+  const home = input.home ?? env.HOME ?? "";
+  const cwd = input.cwd ?? process.cwd();
+  const osHostname = input.osHostname ?? safeEnvValue(env.HOSTNAME) ?? nodeHostname();
+  const user = input.user ?? safeEnvValue(env.USER) ?? safeUserName();
+  const vault = input.vault ?? safeEnvValue(env.WIKI_PATH);
+  const file = input.file ?? (vault ? join(vault, FLEET_REL_PATH) : void 0);
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const loaded = file ? await loadFleetManifest(file) : { ok: false, error: "FILE_NOT_FOUND" };
+  if (!loaded.ok) {
+    const warnings = ["fleet manifest unavailable or invalid"];
+    const markdown2 = formatUnknownContext({
+      generatedAt,
+      osHostname,
+      user,
+      cwd,
+      vault,
+      reason: warnings[0],
+      trace: [],
+      warnings
+    });
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        manifest_loaded: false,
+        generated_at: generatedAt,
+        identity_status: "unknown",
+        resolver_trace: [],
+        warnings,
+        markdown: markdown2,
+        humanHint: markdown2
+      })
+    };
+  }
+  const resolved = await resolveFleetHostId({
+    manifest: loaded.manifest,
+    hostId: input.hostId,
+    env,
+    home,
+    osHostname
+  });
+  if (resolved.hostId && !loaded.manifest.hosts[resolved.hostId]) {
+    const source = resolved.source ?? "unknown";
+    const warnings = [`resolved host id \`${resolved.hostId}\` from ${source} is not in fleet.yaml`];
+    const markdown2 = formatInvalidContext({
+      generatedAt,
+      hostId: resolved.hostId,
+      source,
+      osHostname,
+      user,
+      cwd,
+      vault,
+      trace: resolved.trace,
+      warnings
+    });
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        manifest_loaded: true,
+        host_id: resolved.hostId,
+        source: resolved.source,
+        generated_at: generatedAt,
+        identity_status: "invalid",
+        resolver_trace: resolved.trace,
+        warnings,
+        markdown: markdown2,
+        humanHint: markdown2
+      })
+    };
+  }
+  if (!resolved.hostId) {
+    const warnings = ["host identity is unresolved"];
+    const markdown2 = formatUnknownContext({
+      generatedAt,
+      osHostname,
+      user,
+      cwd,
+      vault,
+      reason: warnings[0],
+      trace: resolved.trace,
+      warnings
+    });
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        manifest_loaded: true,
+        generated_at: generatedAt,
+        identity_status: "unknown",
+        resolver_trace: resolved.trace,
+        warnings,
+        markdown: markdown2,
+        humanHint: markdown2
+      })
+    };
+  }
+  const markdown = formatKnownContext({
+    manifest: loaded.manifest,
+    hostId: resolved.hostId,
+    source: resolved.source,
+    generatedAt,
+    osHostname,
+    user,
+    cwd,
+    vault,
+    trace: resolved.trace
+  });
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      manifest_loaded: true,
+      host_id: resolved.hostId,
+      source: resolved.source,
+      generated_at: generatedAt,
+      identity_status: "known",
+      resolver_trace: resolved.trace,
+      warnings: [],
+      markdown,
+      humanHint: markdown
+    })
+  };
+}
+function fleetContextEnv(input) {
+  const env = input.env ?? process.env;
+  const home = input.home ?? env.HOME ?? "";
+  const osHostname = input.osHostname ?? safeEnvValue(env.HOSTNAME) ?? nodeHostname();
+  const vault = input.vault ?? safeEnvValue(env.WIKI_PATH);
+  const file = input.file ?? (vault ? join(vault, FLEET_REL_PATH) : void 0);
+  return { env, home, osHostname, vault, file };
+}
+async function loadFleetManifestAndHost(input) {
+  const { env, home, osHostname, file } = fleetContextEnv(input);
+  if (!file) return null;
+  const loaded = await loadFleetManifest(file);
+  if (!loaded.ok) return null;
+  const resolved = await resolveFleetHostId({
+    manifest: loaded.manifest,
+    hostId: input.hostId,
+    env,
+    home,
+    osHostname
+  });
+  if (!resolved.hostId) {
+    return {
+      manifest: loaded.manifest,
+      hostId: void 0,
+      source: resolved.source,
+      warnings: ["host identity is unresolved"],
+      identityStatus: "unknown"
+    };
+  }
+  if (!loaded.manifest.hosts[resolved.hostId]) {
+    const source = resolved.source ?? "unknown";
+    return {
+      manifest: loaded.manifest,
+      hostId: resolved.hostId,
+      source: resolved.source,
+      warnings: [`resolved host id \`${resolved.hostId}\` from ${source} is not in fleet.yaml`],
+      identityStatus: "invalid"
+    };
+  }
+  return {
+    manifest: loaded.manifest,
+    hostId: resolved.hostId,
+    source: resolved.source,
+    warnings: [],
+    identityStatus: "known"
+  };
+}
+function snapshotterAliasForLocalHost(fleetLoad) {
+  if (!fleetLoad?.manifest || !fleetLoad.hostId) return void 0;
+  const snapshotterId = Object.entries(fleetLoad.manifest.hosts).find(([, h]) => h.role === "snapshotter")?.[0];
+  if (!snapshotterId) return void 0;
+  const profile = fleetLoad.manifest.hosts[snapshotterId]?.access?.from?.[fleetLoad.hostId];
+  if (!profile || profile.status !== "configured" && profile.status !== "local") return void 0;
+  const aliases = profile.ssh_aliases ?? [];
+  return aliases.length > 0 ? aliases[0] : void 0;
+}
+function satelliteGateFromFleetLoad(load) {
+  if (!load?.hostId) return { satelliteExpected: false };
+  const host = load.manifest.hosts[load.hostId];
+  if (!host) return { satelliteExpected: false };
+  return { satelliteExpected: host.maintenance?.skillwiki_satellite?.enabled === true };
+}
+async function loadFleetManifest(file) {
+  let text;
+  try {
+    text = await readFile2(file, "utf8");
+  } catch {
+    return { ok: false, error: "FILE_NOT_FOUND" };
+  }
+  let parsed;
+  try {
+    parsed = yaml.load(text, { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    return { ok: false, error: "INVALID_YAML", detail: error instanceof Error ? error.message : String(error) };
+  }
+  const result = FleetManifestSchema.safeParse(parsed);
+  if (!result.success) {
+    return { ok: false, error: "INVALID_FLEET_MANIFEST", detail: result.error.issues };
+  }
+  return { ok: true, manifest: result.data };
+}
+function invalidFleet(errors) {
+  return {
+    exitCode: ExitCode.FLEET_MANIFEST_INVALID,
+    result: ok({
+      valid: false,
+      errors,
+      warnings: [],
+      host_count: 0,
+      humanHint: `INVALID fleet manifest
+${errors.map((e) => `  ${e.path || "(root)"}: ${e.message}`).join("\n")}`
+    })
+  };
+}
+function fleetLoadErrors(loaded) {
+  if (loaded.error === "INVALID_YAML") {
+    return [{ path: "", message: `invalid YAML: ${String(loaded.detail ?? "parse failed")}` }];
+  }
+  if (loaded.error === "INVALID_FLEET_MANIFEST" && Array.isArray(loaded.detail)) {
+    return loaded.detail.map((issue) => {
+      const zodIssue = issue;
+      return {
+        path: (zodIssue.path ?? []).join("."),
+        message: zodIssue.message ?? "invalid value"
+      };
+    });
+  }
+  return [{ path: "", message: loaded.error }];
+}
+function fleetWarnings(manifest) {
+  const warnings = [];
+  for (const [id, host] of Object.entries(manifest.hosts)) {
+    if (host.role === "snapshotter" && host.protected !== true) {
+      warnings.push(`snapshotter host '${id}' is not protected=true`);
+    }
+  }
+  return warnings;
+}
+function findSnapshotter(manifest) {
+  return Object.entries(manifest.hosts).find(([, host]) => host.role === "snapshotter")?.[0];
+}
+async function resolveFleetHostId(input) {
+  const trace = [];
+  if (input.hostId) {
+    trace.push({ source: "--host-id", status: "matched", value: input.hostId });
+    return { hostId: input.hostId, source: "host-id", trace };
+  }
+  trace.push({ source: "--host-id", status: "unset" });
+  if (input.env.SKILLWIKI_HOST_ID) {
+    trace.push({ source: "SKILLWIKI_HOST_ID", status: "matched", value: input.env.SKILLWIKI_HOST_ID });
+    return { hostId: input.env.SKILLWIKI_HOST_ID, source: "SKILLWIKI_HOST_ID", trace };
+  }
+  trace.push({ source: "SKILLWIKI_HOST_ID", status: "unset" });
+  if (input.env.AGENT_HOST_ID) {
+    trace.push({ source: "AGENT_HOST_ID", status: "matched", value: input.env.AGENT_HOST_ID });
+    return { hostId: input.env.AGENT_HOST_ID, source: "AGENT_HOST_ID", trace };
+  }
+  trace.push({ source: "AGENT_HOST_ID", status: "unset" });
+  if (input.home) {
+    const dotenv = await parseDotenvFile(join(input.home, ".skillwiki", ".env"));
+    if (dotenv.SKILLWIKI_HOST_ID) {
+      trace.push({ source: "~/.skillwiki/.env:SKILLWIKI_HOST_ID", status: "matched", value: dotenv.SKILLWIKI_HOST_ID });
+      return { hostId: dotenv.SKILLWIKI_HOST_ID, source: "~/.skillwiki/.env:SKILLWIKI_HOST_ID", trace };
+    }
+    trace.push({ source: "~/.skillwiki/.env:SKILLWIKI_HOST_ID", status: "unset" });
+  } else {
+    trace.push({ source: "~/.skillwiki/.env:SKILLWIKI_HOST_ID", status: "skipped" });
+  }
+  if (input.env.VS_HOSTNAME) {
+    trace.push({ source: "VS_HOSTNAME", status: "matched", value: input.env.VS_HOSTNAME });
+    return { hostId: input.env.VS_HOSTNAME, source: "VS_HOSTNAME", trace };
+  }
+  trace.push({ source: "VS_HOSTNAME", status: "unset" });
+  const hostname = input.osHostname.trim();
+  if (hostname) {
+    if (input.manifest.hosts[hostname]) {
+      trace.push({ source: "hostname", status: "matched", value: hostname });
+      return { hostId: hostname, source: "hostname", trace };
+    }
+    const byHostname = Object.entries(input.manifest.hosts).find(([, host]) => host.identity.hostnames.includes(hostname));
+    if (byHostname) {
+      trace.push({ source: "hostname", status: "matched", value: hostname });
+      return { hostId: byHostname[0], source: "hostname", trace };
+    }
+    trace.push({ source: "hostname", status: "unmatched", value: hostname });
+  } else {
+    trace.push({ source: "hostname", status: "unset" });
+  }
+  return { trace };
+}
+function formatKnownContext(input) {
+  const host = input.manifest.hosts[input.hostId];
+  const protectedValue = host.protected === true ? "true" : "false";
+  const writesTo = host.writes_to.join(", ");
+  const selfAliases = collectSelfAliases(input.manifest, input.hostId);
+  const outbound = collectOutboundAccess(input.manifest, input.hostId);
+  const maintenanceLines = formatMaintenanceLines(host);
+  const guidance = host.role === "snapshotter" && host.protected === true ? `this session is already on \`${input.hostId}\`; this is a protected snapshotter host. Live-vault authoring at the resolved \`skillwiki path\` is allowed here. Do not mutate snapshot worktrees or repo-local project workspaces from this session except explicitly approved snapshot maintenance. Keep release-validation workflows read-only when they are documented as such.` : input.hostId === "macos-dev" ? "use declared SSH aliases for remote work when needed; do not assume undeclared hosts have reciprocal SSH access." : `this session is already on \`${input.hostId}\`; do not SSH to self aliases unless the user explicitly asks. Do not assume outbound SSH to other fleet hosts is configured.`;
+  return [
+    "## Runtime Host Context",
+    "",
+    `- Context generated: \`${input.generatedAt}\``,
+    `- Current machine: \`${input.hostId}\`${input.source ? ` (source: \`${input.source}\`)` : ""}`,
+    "- Identity status: `known`",
+    `- Identity resolution: ${formatResolution(input.source, input.hostId)}`,
+    `- Resolver trace: ${formatTrace(input.trace)}`,
+    `- OS hostname: ${formatMaybe(input.osHostname)}`,
+    `- User: ${formatMaybe(input.user)}`,
+    `- Workspace: ${formatMaybe(input.cwd)}`,
+    `- Vault: ${formatMaybe(input.vault)}`,
+    "- Remote freshness: not checked by `fleet context`; run `sync status` or presync before host-sensitive work.",
+    `- Fleet role: \`${host.role}\`; protected: \`${protectedValue}\`; writes_to: \`${writesTo}\``,
+    ...maintenanceLines,
+    `- Self SSH aliases known in fleet: ${formatList(selfAliases)}`,
+    `- Declared outbound SSH from this source: ${formatOutboundAccess(outbound)}`,
+    `- Guidance: ${guidance}`
+  ].join("\n");
+}
+function formatUnknownContext(input) {
+  return [
+    "## Runtime Host Context",
+    "",
+    `- Context generated: \`${input.generatedAt}\``,
+    "- Current machine: unknown",
+    "- Identity status: `unknown`",
+    `- Resolver trace: ${formatTrace(input.trace)}`,
+    `- Warnings: ${formatWarnings(input.warnings)}`,
+    `- OS hostname: ${formatMaybe(input.osHostname)}`,
+    `- User: ${formatMaybe(input.user)}`,
+    `- Workspace: ${formatMaybe(input.cwd)}`,
+    `- Vault: ${formatMaybe(input.vault)}`,
+    "- Remote freshness: not checked by `fleet context`; run `sync status` or presync before host-sensitive work.",
+    "- Fleet role: unknown",
+    "- Self SSH aliases known in fleet: unknown",
+    "- Declared outbound SSH from this source: unknown",
+    `- Guidance: ${input.reason}; do not assume local vs remote role. Inspect runtime or ask before SSH/deploy/sync work.`
+  ].join("\n");
+}
+function formatInvalidContext(input) {
+  return [
+    "## Runtime Host Context",
+    "",
+    `- Context generated: \`${input.generatedAt}\``,
+    "- Current machine: unknown",
+    "- Identity status: `invalid`",
+    `- Identity resolution: ${formatResolution(input.source, input.hostId)}`,
+    `- Resolver trace: ${formatTrace(input.trace)}`,
+    `- Warnings: ${formatWarnings(input.warnings)}`,
+    `- OS hostname: ${formatMaybe(input.osHostname)}`,
+    `- User: ${formatMaybe(input.user)}`,
+    `- Workspace: ${formatMaybe(input.cwd)}`,
+    `- Vault: ${formatMaybe(input.vault)}`,
+    "- Remote freshness: not checked by `fleet context`; run `sync status` or presync before host-sensitive work.",
+    "- Fleet role: unknown",
+    "- Self SSH aliases known in fleet: unknown",
+    "- Declared outbound SSH from this source: unknown",
+    `- Guidance: do not trust this identity; rerun with \`--host-id\` only if the user confirms \`${input.hostId}\` is the current fleet host id.`
+  ].join("\n");
+}
+function collectSelfAliases(manifest, hostId) {
+  const aliases = [];
+  const host = manifest.hosts[hostId];
+  const access = host?.access?.from ?? {};
+  for (const profile of Object.values(access)) {
+    for (const alias of profile.ssh_aliases ?? []) aliases.push(alias);
+  }
+  return [...new Set(aliases)];
+}
+function collectOutboundAccess(manifest, sourceHostId) {
+  const hosts = [];
+  for (const [targetId, target] of Object.entries(manifest.hosts)) {
+    if (targetId === sourceHostId) continue;
+    const profile = target.access?.from?.[sourceHostId];
+    if (profile && (profile.status === "configured" || profile.status === "local")) {
+      hosts.push({
+        hostId: targetId,
+        sshAliases: [...new Set(profile.ssh_aliases ?? [])],
+        users: [...new Set(profile.users ?? [])]
+      });
+    }
+  }
+  return hosts.sort((left, right) => left.hostId.localeCompare(right.hostId));
+}
+function formatMaintenanceLines(host) {
+  const satellite = host.maintenance?.skillwiki_satellite;
+  if (!satellite?.enabled) return [];
+  return [
+    `- Maintenance role: \`skillwiki satellite\`; user: \`${satellite.user}\`; ssh: \`${satellite.ssh_alias}\``,
+    `- Maintenance paths: maintenance vault: \`${satellite.vault_path}\`; repo: \`${satellite.repo_path}\`; scheduler: \`${satellite.scheduler}\`; jobs: ${formatList(satellite.jobs)}`
+  ];
+}
+function formatOutboundAccess(values) {
+  if (values.length === 0) return "none";
+  return values.map((value) => {
+    const aliasPart = value.sshAliases.length > 0 ? ` via ${formatList(value.sshAliases)}` : " (no SSH aliases)";
+    const usersPart = value.users.length > 0 ? ` (users: ${formatList(value.users)})` : "";
+    return `\`${value.hostId}\`${aliasPart}${usersPart}`;
+  }).join("; ");
+}
+function formatResolution(source, hostId) {
+  return source ? `\`${source === "host-id" ? "--host-id" : source}\` -> \`${hostId}\`` : `unknown -> \`${hostId}\``;
+}
+function formatTrace(values) {
+  if (values.length === 0) return "not available";
+  return values.map((value) => {
+    const source = `\`${value.source}\``;
+    if (value.status === "matched") return `${source} matched \`${value.value ?? ""}\``;
+    if (value.status === "unmatched") return `${source} unmatched \`${value.value ?? ""}\``;
+    return `${source} ${value.status}`;
+  }).join("; ");
+}
+function formatWarnings(values) {
+  return values.length > 0 ? values.join("; ") : "none";
+}
+function formatList(values) {
+  return values.length > 0 ? values.map((v) => `\`${v}\``).join(", ") : "none";
+}
+function formatMaybe(value) {
+  return value && value.trim().length > 0 ? `\`${value}\`` : "unknown";
+}
+function safeEnvValue(value) {
+  return value && value.trim().length > 0 ? value : void 0;
+}
+function safeUserName() {
+  try {
+    return userInfo().username;
+  } catch {
+    return "";
+  }
+}
+
+// src/utils/git.ts
+import { execFileSync } from "child_process";
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return "";
+  }
+}
+function gitStrict(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
+// src/utils/operation-journal.ts
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "fs";
+import { join as join2 } from "path";
+function journalDir(vault) {
+  const gitPath = git(vault, ["rev-parse", "--git-path", "vault-sync/operations"]);
+  if (!gitPath) return null;
+  return gitPath.startsWith("/") ? gitPath : join2(vault, gitPath);
+}
+function parseJournalEnv(text) {
+  return Object.fromEntries(
+    text.split("\n").filter((line) => line.includes("=")).map((line) => {
+      const i = line.indexOf("=");
+      return [line.slice(0, i), line.slice(i + 1)];
+    })
+  );
+}
+function serializeJournalEnv(fields, preferredOrder = []) {
+  const keys = [...preferredOrder.filter((k) => k in fields), ...Object.keys(fields).filter((k) => !preferredOrder.includes(k))];
+  const seen = /* @__PURE__ */ new Set();
+  const lines = [];
+  for (const k of keys) {
+    if (seen.has(k)) continue;
+    seen.add(k);
+    lines.push(`${k}=${fields[k]}`);
+  }
+  return lines.join("\n") + "\n";
+}
+function readJournal(vault, opId) {
+  const dir = journalDir(vault);
+  if (!dir) return null;
+  const path = join2(dir, `${opId}.env`);
+  if (!existsSync(path)) return null;
+  try {
+    return parseJournalEnv(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeJournal(vault, opId, fields) {
+  const dir = journalDir(vault);
+  if (!dir) return false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const path = join2(dir, `${opId}.env`);
+    const tmp = `${path}.tmp.${process.pid}`;
+    const order = [
+      "operation_id",
+      "phase",
+      "retry_count",
+      "original_branch",
+      "original_head",
+      "target_oid",
+      "owned_stash_oid",
+      "preservation_scope",
+      "lock_identity",
+      "helper_version",
+      "deployed_runtime_hash",
+      "conflict_identity",
+      "handoff",
+      "reason",
+      "prior_reason",
+      "superseded_at",
+      "cleared_reason",
+      "cleared_by",
+      "worktree_path",
+      "worktree_git_dir",
+      "inventory_path"
+    ];
+    writeFileSync(tmp, serializeJournalEnv(fields, order), "utf8");
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function listJournalOpIds(vault) {
+  const dir = journalDir(vault);
+  if (!dir || !existsSync(dir)) return [];
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith(".env")).map((f) => f.replace(/\.env$/, "")).sort();
+  } catch {
+    return [];
+  }
+}
+function listReviewRequiredOps(vault) {
+  const currentGitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
+  const out = [];
+  for (const opId of listJournalOpIds(vault)) {
+    const fields = readJournal(vault, opId);
+    if (!fields) continue;
+    if (fields.phase !== "review-required" || fields.handoff !== "1") continue;
+    const journalGitDir = fields.worktree_git_dir ?? "";
+    if (!journalGitDir || !currentGitDir || journalGitDir === currentGitDir) {
+      out.push({ opId, fields });
+    }
+  }
+  return out;
+}
+function findReviewRequiredOp(vault) {
+  return listReviewRequiredOps(vault)[0]?.opId;
+}
+function hasUnmergedPaths(vault) {
+  const unmergedRaw = git(vault, ["diff", "--name-only", "--diff-filter=U"]);
+  return unmergedRaw ? unmergedRaw.split("\n").map((s) => s.trim()).filter(Boolean) : [];
+}
+function hasActiveGitSequencer(vault) {
+  const gitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
+  if (!gitDir) return false;
+  for (const m of ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"]) {
+    if (existsSync(join2(gitDir, m))) return true;
+  }
+  if (existsSync(join2(gitDir, "rebase-merge")) || existsSync(join2(gitDir, "rebase-apply"))) {
+    return true;
+  }
+  return false;
+}
+function isWorktreeClean(vault) {
+  const porcelain = git(vault, ["status", "--porcelain"]);
+  return !porcelain || porcelain.trim() === "";
+}
+function canSupersedeJournal(vault, fields) {
+  if (hasUnmergedPaths(vault).length > 0) return false;
+  if (hasActiveGitSequencer(vault)) return false;
+  if (!isWorktreeClean(vault)) return false;
+  const target = fields.target_oid?.trim();
+  if (!target) return false;
+  const head = git(vault, ["rev-parse", "HEAD"]);
+  if (!head) return false;
+  return gitMergeBaseIsAncestor(vault, target, head);
+}
+function gitMergeBaseIsAncestor(vault, ancestor, tip) {
+  if (ancestor === tip) return true;
+  const mb = git(vault, ["merge-base", ancestor, tip]);
+  return mb !== "" && mb === ancestor;
+}
+function markJournalSuperseded(vault, opId, fields, by) {
+  const next = { ...fields };
+  if (next.reason && next.reason !== "superseded-stale-review-required") {
+    next.prior_reason = next.prior_reason || next.reason;
+  }
+  next.phase = "complete";
+  next.reason = "superseded-stale-review-required";
+  next.superseded_at = (/* @__PURE__ */ new Date()).toISOString();
+  next.cleared_by = by;
+  next.cleared_reason = `operator-or-preflight ${next.superseded_at}`;
+  if (!next.handoff) next.handoff = "1";
+  if (!next.operation_id) next.operation_id = opId;
+  return writeJournal(vault, opId, next);
+}
+function supersedeStaleReviewRequiredJournals(vault, opts = {}) {
+  const by = opts.by ?? "skillwiki-preflight";
+  const superseded = [];
+  const skipped = [];
+  if (hasUnmergedPaths(vault).length > 0 || hasActiveGitSequencer(vault) || !isWorktreeClean(vault)) {
+    for (const { opId } of listReviewRequiredOps(vault)) skipped.push(opId);
+    return { superseded, skipped };
+  }
+  for (const { opId, fields } of listReviewRequiredOps(vault)) {
+    if (!canSupersedeJournal(vault, fields)) {
+      skipped.push(opId);
+      continue;
+    }
+    if (opts.dryRun) {
+      superseded.push(opId);
+      continue;
+    }
+    if (markJournalSuperseded(vault, opId, fields, by)) {
+      superseded.push(opId);
+    } else {
+      skipped.push(opId);
+    }
+  }
+  return { superseded, skipped };
+}
+
+// src/utils/vault-sync-helper.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { homedir, platform } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath } from "url";
+var HELPER_NAME = "wiki-pull-with-auto-resolve.sh";
+function candidateHelperPaths(input = { vault: "" }) {
+  const env = input.env ?? process.env;
+  const paths = [];
+  if (input.helperPath) paths.push(input.helperPath);
+  if (env.SKILLWIKI_VAULT_SYNC_PULL_HELPER) paths.push(env.SKILLWIKI_VAULT_SYNC_PULL_HELPER);
+  let here = input.moduleDir;
+  if (!here) {
+    try {
+      here = dirname2(fileURLToPath(import.meta.url));
+    } catch {
+      here = void 0;
+    }
+  }
+  if (here) {
+    paths.push(join3(here, "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "..", "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "..", "..", "vault-sync", "scripts", HELPER_NAME));
+  }
+  const home = input.home ?? env.HOME ?? env.USERPROFILE ?? (() => {
+    try {
+      return homedir();
+    } catch {
+      return void 0;
+    }
+  })();
+  if (home) {
+    const xdg = env.XDG_DATA_HOME;
+    const isDarwin = platform() === "darwin";
+    if (isDarwin) {
+      paths.push(join3(home, "Library", "Application Support", "vault-sync", "bin", HELPER_NAME));
+    }
+    paths.push(join3(xdg || join3(home, ".local", "share"), "vault-sync", "bin", HELPER_NAME));
+    if (!isDarwin) {
+      paths.push(join3(home, "Library", "Application Support", "vault-sync", "bin", HELPER_NAME));
+    }
+  }
+  return paths;
+}
+function resolveVaultSyncPullHelper(input) {
+  for (const p of candidateHelperPaths(input)) {
+    if (p && existsSync2(p)) return p;
+  }
+  return null;
+}
+async function runVaultSyncPullHelper(input) {
+  const helperPath = resolveVaultSyncPullHelper(input);
+  if (!helperPath) {
+    const tried = candidateHelperPaths(input).filter(Boolean);
+    return err("GIT_PULL_FAILED", {
+      message: "canonical vault-sync pull helper not found; run skillwiki doctor; install skillwiki@0.10.1+ or set SKILLWIKI_VAULT_SYNC_PULL_HELPER; host install: ~/Library/Application Support/vault-sync/bin or ~/.local/share/vault-sync/bin",
+      tried_paths: tried.slice(0, 12)
+    });
+  }
+  const remote = input.remote ?? "origin";
+  const branch = input.branch ?? "main";
+  const beforeOid = git(input.vault, ["rev-parse", "HEAD"]);
+  if (!beforeOid) {
+    return err("GIT_PULL_FAILED", { message: "could not read HEAD before pull" });
+  }
+  const env = {
+    ...process.env,
+    ...input.env ?? {},
+    WIKI_DIR: input.vault
+  };
+  if (input.lockToken) {
+    env.VAULT_SYNC_MANAGED_LOCK_TOKEN = input.lockToken;
+  }
+  const result = spawnSync("bash", [helperPath, remote, branch], {
+    env,
+    encoding: "utf8",
+    cwd: input.vault
+  });
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  const status = result.status ?? 1;
+  if (status === 2) {
+    return err("PREFLIGHT_FAILED", { reason: "existing-handoff", output, helper_path: helperPath });
+  }
+  if (status !== 0) {
+    return err("GIT_PULL_FAILED", {
+      message: result.error ? String(result.error) : `helper exited ${status}`,
+      output,
+      helper_path: helperPath
+    });
+  }
+  const afterOid = git(input.vault, ["rev-parse", "HEAD"]);
+  if (!afterOid) {
+    return err("GIT_PULL_FAILED", { message: "could not read HEAD after pull", helper_path: helperPath });
+  }
+  return ok({
+    before_oid: beforeOid,
+    after_oid: afterOid,
+    changed: beforeOid !== afterOid,
+    helper_path: helperPath
+  });
+}
+
+export {
+  CONFIG_KEYS,
+  isValidWikiProfileKey,
+  profileKey,
+  parseDotenvText,
+  parseDotenvFile,
+  writeDotenv,
+  FLEET_REL_PATH,
+  runFleetValidate,
+  runFleetContext,
+  loadFleetManifestAndHost,
+  snapshotterAliasForLocalHost,
+  satelliteGateFromFleetLoad,
+  loadFleetManifest,
+  resolveFleetHostId,
+  git,
+  gitStrict,
+  readJournal,
+  listJournalOpIds,
+  listReviewRequiredOps,
+  findReviewRequiredOp,
+  hasUnmergedPaths,
+  hasActiveGitSequencer,
+  supersedeStaleReviewRequiredJournals,
+  resolveVaultSyncPullHelper,
+  runVaultSyncPullHelper
+};