@workit-dev/core 0.0.1 → 1.0.0

package/src/core/workit-paths.mjs

@@ -0,0 +1,242 @@
+// The one resolver for every Workit file location (docs/agents/file-locations.md).
+// Kinds: config, state, data, cache and runtime. Linux and macOS follow the
+// XDG Base Directory spec; Windows uses %APPDATA% (config, roaming) and
+// %LOCALAPPDATA% (state, data, cache). An absolute XDG_*_HOME wins on every
+// platform; a relative one is ignored, as the spec says.
+//
+// Plain JavaScript with node: builtins only and no syntax newer than Node 16:
+// TypeScript imports it, and the hook launchers carry a byte-equal copy
+// (claude-code bin/, codex bin/, cursor hooks/; a test holds them equal). The
+// POSIX shell launchers embed the *_SH functions below verbatim, and a test
+// runs them against the JavaScript for the same environment.
+// Side-effect free on import; only migrateLegacyDirs touches the disk.
+import { existsSync, lstatSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Every location kind the resolver knows. */
+export const WORKIT_DIR_KINDS = ["config", "state", "data", "cache", "runtime"];
+
+/** Environment overrides per kind, first non-empty wins; each names the directory itself. */
+export const WORKIT_DIR_OVERRIDES = {
+  config: ["WORKIT_CONFIG", "WORKIT_CONFIG_DIR"],
+  state: ["WORKIT_STATE_DIR"],
+  data: [],
+  cache: [],
+  runtime: [],
+};
+
+/** The XDG base variable each kind follows (`<base>/workit`). */
+export const WORKIT_DIR_XDG = {
+  config: "XDG_CONFIG_HOME",
+  state: "XDG_STATE_HOME",
+  data: "XDG_DATA_HOME",
+  cache: "XDG_CACHE_HOME",
+  runtime: "XDG_RUNTIME_DIR",
+};
+
+/** The XDG defaults under $HOME when the base variable is unset. */
+const XDG_DEFAULTS = {
+  config: [".config"],
+  state: [".local", "state"],
+  data: [".local", "share"],
+  cache: [".cache"],
+};
+
+/**
+ * The user's home: $HOME, else %USERPROFILE%, else the OS record.
+ * @param {NodeJS.ProcessEnv} env
+ */
+export const userHome = (env) => env.HOME || env.USERPROFILE || os.homedir();
+
+/**
+ * The kind's XDG base when set to an absolute path (the spec ignores a relative one).
+ * @param {string} kind @param {NodeJS.ProcessEnv} env
+ */
+const xdgBase = (kind, env) => {
+  const base = env[WORKIT_DIR_XDG[kind]];
+  return base && path.isAbsolute(base) ? base : "";
+};
+
+/**
+ * Where one kind of Workit file lives.
+ * @param {"config" | "state" | "data" | "cache" | "runtime"} kind
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [platform]
+ * @returns {string}
+ */
+export const workitDir = (kind, env = process.env, platform = process.platform) => {
+  for (const name of WORKIT_DIR_OVERRIDES[kind]) if (env[name]) return String(env[name]);
+  const base = xdgBase(kind, env);
+  if (base) return path.join(base, "workit");
+  if (kind === "runtime") {
+    if (platform === "win32") return path.join(env.TEMP || env.TMP || os.tmpdir(), "workit");
+    const uid = typeof process.getuid === "function" ? process.getuid() : os.userInfo().username;
+    return path.join(env.TMPDIR || os.tmpdir(), `workit-${uid}`);
+  }
+  const home = userHome(env);
+  if (platform !== "win32") return path.join(home, ...XDG_DEFAULTS[kind], "workit");
+  if (kind === "config")
+    return path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "workit");
+  const local = path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "workit");
+  return kind === "cache" ? path.join(local, "cache") : local;
+};
+
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const configDir = (env, platform) => workitDir("config", env, platform);
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const stateDir = (env, platform) => workitDir("state", env, platform);
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const dataDir = (env, platform) => workitDir("data", env, platform);
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const cacheDir = (env, platform) => workitDir("cache", env, platform);
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const runtimeDir = (env, platform) => workitDir("runtime", env, platform);
+
+/**
+ * Where Workit keeps the worktrees it manages: `<state>/worktrees/<repo>/<slug>`.
+ * State, not cache: a worktree holds uncommitted work.
+ * @param {NodeJS.ProcessEnv} [env] @param {string} [platform]
+ */
+export const worktreesDir = (env, platform) => path.join(stateDir(env, platform), "worktrees");
+
+/**
+ * The managed worktree root before it moved to worktreesDir:
+ * `$XDG_CACHE_HOME/workit-wt`, else `~/.cache/workit-wt` (on every platform).
+ * Never moved (a session may be using a worktree there); cleanup still sweeps it.
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export const legacyWorktreesDir = (env = process.env) =>
+  path.join(xdgBase("cache", env) || path.join(userHome(env), ".cache"), "workit-wt");
+
+/**
+ * The POSIX shell form of stateDir, embedded verbatim by the shell launchers
+ * (claude-code bin/workit, the owned launcher `workit upgrade` writes).
+ */
+export const STATE_DIR_SH = `workit_state_dir() {
+  if [ -n "\${WORKIT_STATE_DIR:-}" ]; then printf '%s\\n' "$WORKIT_STATE_DIR"; return; fi
+  case "\${XDG_STATE_HOME:-}" in /*) printf '%s\\n' "$XDG_STATE_HOME/workit"; return ;; esac
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*) printf '%s\\n' "\${LOCALAPPDATA:-$HOME/AppData/Local}/workit" ;;
+    *) printf '%s\\n' "$HOME/.local/state/workit" ;;
+  esac
+}`;
+
+/** The POSIX shell form of configDir, embedded verbatim by scripts/lib/config-dir.sh. */
+export const CONFIG_DIR_SH = `workit_config_dir() {
+  if [ -n "\${WORKIT_CONFIG:-}" ]; then printf '%s\\n' "$WORKIT_CONFIG"; return; fi
+  if [ -n "\${WORKIT_CONFIG_DIR:-}" ]; then printf '%s\\n' "$WORKIT_CONFIG_DIR"; return; fi
+  case "\${XDG_CONFIG_HOME:-}" in /*) printf '%s\\n' "$XDG_CONFIG_HOME/workit"; return ;; esac
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*) printf '%s\\n' "\${APPDATA:-$HOME/AppData/Roaming}/workit" ;;
+    *) printf '%s\\n' "$HOME/.config/workit" ;;
+  esac
+}`;
+
+/** The POSIX shell form of dataDir, embedded verbatim by scripts/lib/config-dir.sh. */
+export const DATA_DIR_SH = `workit_data_dir() {
+  case "\${XDG_DATA_HOME:-}" in /*) printf '%s\\n' "$XDG_DATA_HOME/workit"; return ;; esac
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*) printf '%s\\n' "\${LOCALAPPDATA:-$HOME/AppData/Local}/workit" ;;
+    *) printf '%s\\n' "$HOME/.local/share/workit" ;;
+  esac
+}`;
+
+/**
+ * The POSIX shell form of runtimeDir, embedded verbatim by scripts/lib/config-dir.sh.
+ * `os.tmpdir()` drops a trailing slash from TMPDIR; so does this.
+ */
+export const RUNTIME_DIR_SH = `workit_runtime_dir() {
+  case "\${XDG_RUNTIME_DIR:-}" in /*) printf '%s\\n' "$XDG_RUNTIME_DIR/workit"; return ;; esac
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*) printf '%s\\n' "\${TEMP:-\${TMP:-/tmp}}/workit" ;;
+    *) set -- "\${TMPDIR:-/tmp}"; printf '%s\\n' "\${1%/}/workit-$(id -u)" ;;
+  esac
+}`;
+
+/**
+ * Locations older Workit versions used, per kind, that migrateLegacyDirs moves
+ * to the resolver's default: macOS state lived in ~/Library/Application
+ * Support/workit, Windows config in ~\.config\workit. Only while the kind has
+ * no override or XDG variable (then the default is in use).
+ * @param {NodeJS.ProcessEnv} [env] @param {string} [platform]
+ * @returns {Array<{ kind: "config" | "state", legacy: string, target: string }>}
+ */
+export const legacyDirs = (env = process.env, platform = process.platform) => {
+  const home = userHome(env);
+  /** @type {Array<{ kind: "config" | "state", legacy: string }>} */
+  const old = [];
+  if (platform === "darwin")
+    old.push({
+      kind: "state",
+      legacy: path.join(home, "Library", "Application Support", "workit"),
+    });
+  if (platform === "win32")
+    old.push({ kind: "config", legacy: path.join(home, ".config", "workit") });
+  return old
+    .filter(
+      (entry) =>
+        !WORKIT_DIR_OVERRIDES[entry.kind].some((name) => env[name]) && !xdgBase(entry.kind, env),
+    )
+    .map((entry) => ({
+      kind: entry.kind,
+      legacy: entry.legacy,
+      target: workitDir(entry.kind, env, platform),
+    }));
+};
+
+/** The marker a move leaves beside the old location: `<legacy>.moved-<stamp>`. */
+export const LEGACY_MARKER_INFIX = ".moved-";
+
+/**
+ * A real directory, never a symlink to one: a migration must not move a link
+ * the user made (the data behind it would stay where the link pointed).
+ * @param {string} file
+ */
+export const isRealDir = (file) => {
+  try {
+    return lstatSync(file).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * One-time move of each legacy location whose new location does not exist yet.
+ * Leaves `<legacy>.moved-<UTC stamp>` naming the new location; a second run
+ * finds no legacy directory and does nothing. Never throws: a failed move
+ * leaves both places as they were, and `workit doctor` (legacy_dirs) names the
+ * command that finishes it.
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: string, now?: Date }} [options]
+ * @returns {Array<{ kind: string, legacy: string, target: string, marker: string }>}
+ */
+export const migrateLegacyDirs = (options = {}) => {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const stamp = (options.now || new Date())
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\..*$/, "Z");
+  /** @type {Array<{ kind: string, legacy: string, target: string, marker: string }>} */
+  const moved = [];
+  for (const entry of legacyDirs(env, platform)) {
+    if (!isRealDir(entry.legacy) || existsSync(entry.target)) continue;
+    const marker = `${entry.legacy}${LEGACY_MARKER_INFIX}${stamp}`;
+    try {
+      mkdirSync(path.dirname(entry.target), { recursive: true });
+      renameSync(entry.legacy, entry.target);
+    } catch {
+      continue;
+    }
+    try {
+      writeFileSync(
+        marker,
+        `Workit moved this ${entry.kind} directory to ${entry.target} at ${stamp}.\n`,
+      );
+    } catch {
+      // the move is done; a missing marker only loses the note
+    }
+    moved.push({ kind: entry.kind, legacy: entry.legacy, target: entry.target, marker });
+  }
+  return moved;
+};

package/src/core/workspace-branch-policy.ts

@@ -0,0 +1,123 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { detectBranchPolicy } from "./branch-policy";
+import { configDir } from "./config";
+import {
+  readWorkspacesResult,
+  resolveWorkspaceFrom,
+  validateWorkspaceGlob,
+  validateWorkspacesDocument,
+  workspacesRevision,
+  type WorkspaceConfig,
+} from "./workspaces";
+
+const readFileSafe = (p: string): string | null => {
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+// The one proposal→write path for a workspace branch policy, shared by the
+// OpenCode `workit_init_apply` branch_policy action (init.ts) and the CLI
+// wizard, so both produce byte-identical workspaces.json writes.
+export function applyWorkspaceBranchPolicy(opts: {
+  workspace_root: string;
+  env?: NodeJS.ProcessEnv;
+}): Record<string, any> {
+  const { workspace_root, env = process.env } = opts;
+  const dir = path.join(env.WORKIT_CONFIG ?? configDir());
+  const {
+    status,
+    path: wsPath,
+    entries,
+    document,
+    revision,
+    error: workspacesError,
+  } = readWorkspacesResult(dir);
+  if (status === "malformed" || status === "invalid")
+    return { ok: false, error: workspacesError ?? `invalid workspaces.json: ${wsPath}` };
+  const detection = detectBranchPolicy(workspace_root);
+  const name = String(env.WORKIT_BP_NAME ?? path.basename(workspace_root));
+  const integration = (env.WORKIT_BP_INTEGRATION ?? detection.integration) as "pr" | "merge";
+  const policy = {
+    preset: detection.preset,
+    developBranch: env.WORKIT_BP_DEVELOP ?? detection.developBranch ?? undefined,
+    prefixes: detection.prefixes,
+    allowed: detection.allowed,
+    protected: detection.protected,
+    integration,
+  };
+  const glob = `${workspace_root.replace(/[\\/]+$/, "")}/**`;
+  if (!validateWorkspaceGlob(glob).ok)
+    return { ok: false, error: `invalid workspace glob: ${glob}` };
+  let existing: WorkspaceConfig | null;
+  try {
+    existing = resolveWorkspaceFrom(workspace_root, dir);
+  } catch (error) {
+    const selectedName = env.WORKIT_BP_NAME?.trim();
+    if (!selectedName)
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    try {
+      existing = resolveWorkspaceFrom(workspace_root, dir, selectedName);
+    } catch (selectionError) {
+      return {
+        ok: false,
+        error: selectionError instanceof Error ? selectionError.message : String(selectionError),
+      };
+    }
+  }
+  if (existing?.branchPolicy && isDeepStrictEqual(existing.branchPolicy, policy)) {
+    return {
+      ok: true,
+      status: "already-configured",
+      workspace: existing,
+      policy,
+      config_path: wsPath,
+    };
+  }
+  const next = existing
+    ? entries.map((w) => (w.name === existing?.name ? { ...w, branchPolicy: policy } : w))
+    : [...entries, { name, glob, branchPolicy: policy }];
+  if (!existing && entries.some((entry) => entry.name === name))
+    return { ok: false, error: `workspace name ${JSON.stringify(name)} is already configured` };
+  const proposed = validateWorkspacesDocument({ ...document, workspaces: next }, wsPath);
+  if (proposed.status !== "valid") return { ok: false, error: proposed.error };
+  if (workspacesRevision(readFileSafe(wsPath)) !== revision)
+    return {
+      ok: false,
+      error: `workspaces.json changed while applying the branch policy: ${wsPath}`,
+    };
+  mkdirSync(path.dirname(wsPath), { recursive: true });
+  const tmp = `${wsPath}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify({ ...document, workspaces: next }, null, 2) + "\n", "utf8");
+    if (workspacesRevision(readFileSafe(wsPath)) !== revision) {
+      rmSync(tmp, { force: true });
+      return {
+        ok: false,
+        error: `workspaces.json changed while applying the branch policy: ${wsPath}`,
+      };
+    }
+    renameSync(tmp, wsPath);
+  } catch (error) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {}
+    return {
+      ok: false,
+      error: `failed to write ${wsPath}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  return {
+    ok: true,
+    status: existing ? "updated" : "configured",
+    workspace: existing
+      ? { ...existing, branchPolicy: policy }
+      : { name, glob, branchPolicy: policy },
+    policy,
+    config_path: wsPath,
+  };
+}