@anhlp/alp 0.0.1-beta.3 → 0.0.1-beta.4

package/packages/core/dist/backup.js

@@ -13,10 +13,15 @@ import { STATE_SCHEMA, assertStateSupported, readStateSchema } from "./state-sch
 import { withTaskLock } from "./tasks.js";
 var BACKUP_FORMAT = 1;
 var BACKUP_EXTENSION = ".alpbackup";
-var STATE_UNITS = ["state/schema.json", "state/sessions", "state/timeline", "state/receipts", "state/recall.json", "state/pause.json", "state/trust.json", "state/web-workspaces.json"];
+var RESULT_LEDGER = "state/assignment-results.json";
+var RESULT_MARKER = `${RESULT_LEDGER}.initialized`;
+var DESTINATIONS = "worktree-destinations.json";
+var QUARANTINED_DESTINATIONS = "state/worktree-destinations.quarantined.json";
+var STATE_UNITS = [RESULT_LEDGER, RESULT_MARKER, "state/schema.json", "state/sessions", "state/timeline", "state/receipts", "state/recall.json", "state/pause.json", "state/trust.json", "state/web-workspaces.json"];
 var CLEARED_UNITS = ["state/live.json", "state/migration.json"];
 var HOME_UNITS = [
   ...STATE_UNITS,
+  DESTINATIONS,
   "settings.json",
   "library.json",
   "role-skills.json",
@@ -378,6 +383,98 @@ async function holdTaskLocks(roots, work) {
     clearInterval(touch);
   }
 }
+async function prepareWorkspaceRestore(home, root, units, warnings) {
+  const relevant = [RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, "state/sessions", "state/web-workspaces.json"];
+  const restorable = units.filter((unit) => unit.path !== QUARANTINED_DESTINATIONS);
+  if (!units.some((unit) => relevant.includes(unit.path))) return restorable;
+  for (const base of [home, root]) {
+    const info = await lstat(path.join(base, "state")).catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (info && !info.isDirectory()) throw invalid("workspace state must be a real directory");
+  }
+  const result = restorable.filter((unit) => ![RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, "state/web-workspaces.json"].includes(unit.path));
+  async function regular(base, unit, declared) {
+    if (declared && declared.kind === "absent") return void 0;
+    const file = path.join(base, unit);
+    const info = await lstat(file).catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (!info) {
+      if (declared) throw invalid(`${unit} is declared but missing from the backup`);
+      return void 0;
+    }
+    if (!info.isFile()) throw invalid(`${unit} must be a regular file for a workspace restore`);
+    return readFile(file, "utf8");
+  }
+  const incoming = async (unit) => {
+    const declared = units.find((entry) => entry.path === unit);
+    return declared ? regular(root, unit, declared) : void 0;
+  };
+  const owners = /* @__PURE__ */ new Map();
+  let hasLedger = false;
+  for (const text of [await incoming(RESULT_LEDGER), await regular(home, RESULT_LEDGER)]) {
+    if (text === void 0) continue;
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      throw invalid("assignment result ledger is not readable JSON; repair it before restoring");
+    }
+    const absolute = (value2) => typeof value2 === "string" && path.isAbsolute(value2);
+    if (value?.version !== 1 || !Array.isArray(value.workspaces) || !value.workspaces.every(absolute) || !Array.isArray(value.results) || !value.results.every((entry) => entry && typeof entry.assignmentId === "string" && absolute(entry.checkout) && (entry.worktree === void 0 || absolute(entry.worktree))))
+      throw invalid("assignment result ledger has an unsupported or invalid shape");
+    hasLedger = true;
+    for (const entry of value.results) {
+      const owner = { assignmentId: entry.assignmentId, checkout: entry.checkout, ...entry.worktree === void 0 ? {} : { worktree: entry.worktree } };
+      const previous = owners.get(owner.assignmentId);
+      if (previous && JSON.stringify(previous) !== JSON.stringify(owner)) throw invalid("assignment result ownership conflicts with current data; reconcile it before restoring");
+      owners.set(owner.assignmentId, owner);
+    }
+  }
+  const markers = [await incoming(RESULT_MARKER), await regular(home, RESULT_MARKER)];
+  if (markers.some((text) => text !== void 0 && text !== "1\n")) throw invalid("assignment result initialized marker is invalid");
+  await mkdir(path.join(root, "state"), { recursive: true, mode: 448 });
+  if (hasLedger) await writeAtomic(path.join(root, RESULT_LEDGER), JSON.stringify({ version: 1, workspaces: [], results: [...owners.values()] }) + "\n");
+  result.push({ path: RESULT_LEDGER, kind: hasLedger ? "file" : "absent" });
+  const initialized = markers.some((text) => text !== void 0);
+  if (initialized) await writeAtomic(path.join(root, RESULT_MARKER), "1\n");
+  result.push({ path: RESULT_MARKER, kind: initialized ? "file" : "absent" });
+  const mappings = await incoming(DESTINATIONS);
+  if (mappings !== void 0) {
+    await writeAtomic(path.join(root, QUARANTINED_DESTINATIONS), mappings);
+    result.push({ path: QUARANTINED_DESTINATIONS, kind: "file" });
+  }
+  result.push({ path: DESTINATIONS, kind: "absent" });
+  const registryUnit = "state/web-workspaces.json";
+  const registryDeclaration = units.find((unit) => unit.path === registryUnit);
+  const registryText = registryDeclaration ? await incoming(registryUnit) : await regular(home, registryUnit);
+  if (registryText !== void 0) {
+    let registry;
+    try {
+      registry = JSON.parse(registryText);
+    } catch {
+      throw invalid("workspace registry is not readable JSON; repair it before restoring");
+    }
+    const epoch = `restore-${randomBytes(16).toString("hex")}`;
+    let revoked = false;
+    const revoke = (value) => {
+      if (!value || typeof value !== "object") return;
+      if (Object.hasOwn(value, "grantEpoch")) {
+        value.grantEpoch = epoch;
+        revoked = true;
+      }
+      for (const child of Object.values(value)) revoke(child);
+    };
+    revoke(registry);
+    await writeAtomic(path.join(root, registryUnit), revoked ? JSON.stringify(registry) + "\n" : registryText);
+    result.push({ path: registryUnit, kind: "file" });
+  } else if (registryDeclaration) result.push({ path: registryUnit, kind: "absent" });
+  if (hasLedger || initialized || mappings !== void 0 || await exists(path.join(home, DESTINATIONS))) warnings.push("Workspace restore retains assignment owners but clears checkout birth certification; old targets require an audited migration. Worktree destination mappings are inactive and require explicit host approval; archived mapping evidence is in state/worktree-destinations.quarantined.json. Historical checkout grants remain revoked after reapproval.");
+  return result;
+}
 async function restoreBackup({ home, file, projects = true, safety = true, clearLive = true, replaceNewer = false, by = "alp", beforeSwap }) {
   const interrupted = await recoverInterruptedRestore(home);
   try {
@@ -392,6 +489,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
   const warnings = [];
   const areaBase = (area) => area === "home" ? home : header.projects[Number(area.slice(8))].root;
   const directories = [];
+  let homeUnits;
   const journal = { version: 1, id, file: path.resolve(file), by, startedAt: (/* @__PURE__ */ new Date()).toISOString(), phase: "staging", units: [], staging: [], created: [], locks: [] };
   const record = () => writeAtomic(journalFile(home), JSON.stringify(journal) + "\n");
   const abandon = async () => {
@@ -443,6 +541,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
         };
       }
     });
+    homeUnits = await prepareWorkspaceRestore(home, staging.get("home"), header.units, warnings);
     for (const [directory, mode] of directories.reverse()) if (Number.isSafeInteger(mode)) await chmod(directory, mode & 511 | 448).catch(() => {
     });
   } catch (error) {
@@ -463,8 +562,8 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
   const plan = [];
   for (const [area, root] of staging) {
     const base = areaBase(area);
-    const units = area === "home" ? header.units : header.projects[Number(area.slice(8))].units;
-    const known = area === "home" ? HOME_UNITS : PROJECT_UNITS;
+    const units = area === "home" ? homeUnits : header.projects[Number(area.slice(8))].units;
+    const known = area === "home" ? [...HOME_UNITS, QUARANTINED_DESTINATIONS] : PROJECT_UNITS;
     for (const unit of units) {
       if (!known.includes(unit.path)) {
         warnings.push(`${unit.path} is not a unit this ALP restores; left as it is`);
@@ -489,7 +588,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
   let safetyFile;
   if (safety) {
     try {
-      safetyFile = await automaticBackup(home, "pre-restore", { units: header.units.map((unit) => unit.path).filter((unit) => HOME_UNITS.includes(unit)), projects: roots, by });
+      safetyFile = await automaticBackup(home, "pre-restore", { units: [.../* @__PURE__ */ new Set([...header.units.map((unit) => unit.path), ...homeUnits.map((unit) => unit.path)])].filter((unit) => HOME_UNITS.includes(unit) || unit === QUARANTINED_DESTINATIONS), projects: roots, by });
     } catch (error) {
       await abandon();
       throw new AlpError("RESTORE_SAFETY_BACKUP_FAILED", `could not save the current data before restoring (${error?.message ?? error}); nothing was changed`, { cause: error });

package/packages/core/dist/index.d.ts

@@ -28,3 +28,4 @@ export * as user_settings from "./user-settings.js";
 export * as validation from "./validation.js";
 export * as verify from "./verify.js";
 export * as workflow from "./workflow.js";
+export * as user_worktree from "./user-worktree.js";

package/packages/core/dist/index.js

@@ -29,6 +29,7 @@ import * as user_settings from "./user-settings.js";
 import * as validation from "./validation.js";
 import * as verify from "./verify.js";
 import * as workflow from "./workflow.js";
+import * as user_worktree from "./user-worktree.js";
 export {
   adapter,
   atomic,
@@ -57,6 +58,7 @@ export {
   trust,
   upgrade,
   user_settings,
+  user_worktree,
   validation,
   verify,
   workflow

package/packages/core/dist/migrations.js

@@ -78,7 +78,7 @@ async function migrateState(home, { by = "alp", migrations = MIGRATIONS, target
         throw new AlpError("STATE_MIGRATION_ROLLBACK_FAILED", `state migration ${step.name} failed (${error?.message ?? error}) and putting the state back from ${backup} failed too (${rollback?.message ?? rollback}); the next start tries the migration again. See docs/alp/data-recovery.md`, { cause: error });
       }
       await rm(migrationFile(home), { force: true });
-      throw new AlpError("STATE_MIGRATION_FAILED", `state migration ${step.name} (schema ${step.from} \u2192 ${step.to}) failed: ${error?.message ?? error}; the state was put back from ${backup} and is unchanged. See docs/alp/data-recovery.md`, { cause: error });
+      throw new AlpError("STATE_MIGRATION_FAILED", `state migration ${step.name} (schema ${step.from} \u2192 ${step.to}) failed: ${error?.message ?? error}; data was restored from ${backup} with workspace authority checks. See docs/alp/data-recovery.md`, { cause: error });
     }
     await writeStateSchema(home, step.to, by);
     await rm(migrationFile(home), { force: true });

package/packages/core/dist/user-worktree.d.ts

@@ -0,0 +1,29 @@
+export function repositoryIdentity(directory: any): Promise<{
+    gitDir: string;
+    commonDir: string;
+    branch: string | null;
+}>;
+/** User workspace primitives. Assignment cleanup's force/rm semantics must never be used here. */
+export function userWorktreeGit({ executable, timeoutMs, maxBytes }?: {
+    executable?: string | undefined;
+    timeoutMs?: number | undefined;
+    maxBytes?: number | undefined;
+}): {
+    facts: (source: any) => Promise<{
+        commonDir: string;
+        gitDir: string;
+        head: any;
+        branch: any;
+    }>;
+    inspect: (source: any, target: any, branch: any) => Promise<any>;
+    assertClean: (target: any) => Promise<void>;
+    checkoutFacts(directory: any): Promise<{
+        isGit: true;
+        repoRoot: any;
+        currentBranch: any;
+        remoteUrl: any;
+        isDirty: boolean;
+    }>;
+    create(source: any, parent: any, name: any, branch: any, head: any): Promise<string>;
+    remove(source: any, target: any, branch: any): Promise<void>;
+};

package/packages/core/dist/user-worktree.js

@@ -0,0 +1,242 @@
+// packages/core/src/user-worktree.js
+import { spawn } from "node:child_process";
+import { lstat, realpath, open } from "node:fs/promises";
+import path from "node:path";
+import { constants } from "node:fs";
+async function control(file) {
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.nlink !== 1 || info.size > 4096) throw new Error("Invalid Git administrative file");
+    const bytes = Buffer.alloc(4097);
+    const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+    if (bytesRead > 4096) throw new Error("Git administrative file exceeds limit");
+    return bytes.subarray(0, bytesRead).toString("utf8").replace(/\r?\n$/, "");
+  } finally {
+    await handle.close();
+  }
+}
+async function repositoryIdentity(directory) {
+  if (await realpath(directory) !== directory) throw new Error("Repository root is not canonical");
+  const entry = path.join(directory, ".git");
+  const info = await lstat(entry);
+  let gitDir;
+  if (info.isDirectory()) gitDir = await realpath(entry);
+  else {
+    const value = await control(entry);
+    if (!value.startsWith("gitdir: ") || /[\r\n\0]/.test(value)) throw new Error("Invalid Git control link");
+    gitDir = await realpath(path.resolve(directory, value.slice(8)));
+  }
+  const commonEntry = path.join(gitDir, "commondir");
+  const hasCommon = await lstat(commonEntry).catch((error) => {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  });
+  const commonDir = hasCommon ? await realpath(path.resolve(gitDir, await control(commonEntry))) : gitDir;
+  if (gitDir !== commonDir) {
+    if (path.dirname(gitDir) !== path.join(commonDir, "worktrees") || path.resolve(gitDir, await control(path.join(gitDir, "gitdir"))) !== entry)
+      throw new Error("Git worktree backlink changed");
+  }
+  const head = await control(path.join(gitDir, "HEAD"));
+  const branch = head.startsWith("ref: refs/heads/") ? head.slice(16) : null;
+  if (branch !== null && (!branch || /[\r\n\0]/.test(branch))) throw new Error("Invalid branch reference");
+  return { gitDir, commonDir, branch };
+}
+function userWorktreeGit({ executable = "/usr/bin/git", timeoutMs = 15e3, maxBytes = 2 * 1024 * 1024 } = {}) {
+  if (process.platform === "win32") throw new Error("User worktree operations are unavailable on this host");
+  if (!path.isAbsolute(executable)) throw new Error("Git executable must be host configured and absolute");
+  const disabled = [
+    "-c",
+    "core.hooksPath=/dev/null",
+    "-c",
+    "core.fsmonitor=false",
+    "-c",
+    "core.untrackedCache=false",
+    "-c",
+    "core.pager=cat",
+    "-c",
+    "maintenance.auto=false",
+    "-c",
+    "gc.auto=0",
+    "-c",
+    "protocol.allow=never",
+    "-c",
+    "submodule.recurse=false"
+  ];
+  const env = {
+    PATH: "/usr/bin:/bin",
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_GLOBAL: "/dev/null",
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_OPTIONAL_LOCKS: "0",
+    LANG: "C",
+    LC_ALL: "C"
+  };
+  async function raw(cwd, args, extra = []) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(executable, [...disabled, ...extra, ...args], {
+        cwd,
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        detached: true
+      });
+      let size = 0;
+      let overflow = false;
+      const stdout = [];
+      const stderr = [];
+      const kill = () => {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+          child.kill("SIGKILL");
+        }
+      };
+      const timer = setTimeout(() => {
+        overflow = true;
+        kill();
+      }, timeoutMs);
+      const collect = (sink) => (chunk) => {
+        size += chunk.length;
+        if (size > maxBytes) {
+          overflow = true;
+          kill();
+        } else sink.push(chunk);
+      };
+      child.stdout.on("data", collect(stdout));
+      child.stderr.on("data", collect(stderr));
+      child.once("error", (error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+      child.once("close", (code) => {
+        clearTimeout(timer);
+        if (overflow) reject(new Error("Git operation exceeded its host limit"));
+        else
+          resolve({
+            code,
+            stdout: Buffer.concat(stdout).toString("utf8"),
+            stderr: Buffer.concat(stderr).toString("utf8")
+          });
+      });
+    });
+  }
+  async function filterOverrides(cwd) {
+    const filters = await raw(cwd, [
+      "config",
+      "--null",
+      "--name-only",
+      "--get-regexp",
+      "^filter\\..*\\.(smudge|clean|process|required)$"
+    ]);
+    if (filters.code !== 0 && filters.code !== 1) throw new Error("Cannot inspect repository filters");
+    const neutral = filters.stdout.split("\0").filter(Boolean).flatMap((key) => ["-c", `${key}=${key.endsWith(".required") ? "false" : ""}`]);
+    return neutral;
+  }
+  async function run(cwd, args, extra = []) {
+    return raw(cwd, args, [...await filterOverrides(cwd), ...extra]);
+  }
+  async function checked(cwd, args, extra = []) {
+    const result = await run(cwd, args, extra);
+    if (result.code !== 0) throw new Error("Git workspace operation refused");
+    return result.stdout.trim();
+  }
+  async function directory(value) {
+    const canonical = await realpath(value);
+    if (canonical !== value || !(await lstat(value)).isDirectory())
+      throw new Error("Workspace paths must be canonical directories");
+    return canonical;
+  }
+  async function facts(source) {
+    await directory(source);
+    const top = await checked(source, ["rev-parse", "--show-toplevel"]);
+    if (await realpath(top) !== source) throw new Error("Workspace must be a repository top level");
+    const commonDir = await realpath(
+      await checked(source, ["rev-parse", "--path-format=absolute", "--git-common-dir"])
+    );
+    const identity = await repositoryIdentity(source);
+    if (identity.commonDir !== commonDir) throw new Error("Repository identity changed");
+    const head = await checked(source, ["rev-parse", "--verify", "HEAD"]);
+    const branch = await run(source, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    return { commonDir, gitDir: identity.gitDir, head, branch: branch.code === 0 ? branch.stdout.trim() : null };
+  }
+  async function list(source) {
+    const result = await checked(source, ["worktree", "list", "--porcelain", "-z"]);
+    return result.split("\0\0").filter(Boolean).map(
+      (block) => Object.fromEntries(
+        block.split("\0").filter(Boolean).map((line) => {
+          const i = line.indexOf(" ");
+          return i < 0 ? [line, true] : [line.slice(0, i), line.slice(i + 1)];
+        })
+      )
+    );
+  }
+  async function inspect(source, target, branch) {
+    const row = (await list(source)).find((row2) => row2.worktree === target);
+    if (!row) return void 0;
+    await directory(target);
+    if (row.branch !== `refs/heads/${branch}` || row.locked || row.prunable)
+      throw new Error("Managed worktree identity changed");
+    const origin = await facts(source);
+    const destination = await facts(target);
+    if (origin.commonDir !== destination.commonDir) throw new Error("Managed worktree repository changed");
+    return row;
+  }
+  async function assertClean(target) {
+    const flags = await checked(target, ["ls-files", "-v", "-z"]);
+    if (flags.split("\0").some((row) => row && (row[0] === "S" || /[a-z]/.test(row[0]))))
+      throw new Error("Worktree has hidden index state");
+    if ((await checked(target, ["ls-files", "--stage", "-z"])).split("\0").some((row) => row.startsWith("160000 ")))
+      throw new Error("Worktree has submodules");
+    if ((await checked(target, ["status", "--porcelain=v1", "--untracked-files=all", "--ignored"])).length)
+      throw new Error("Worktree contains uncommitted or ignored files");
+  }
+  return {
+    facts,
+    inspect,
+    assertClean,
+    async checkoutFacts(directory2) {
+      const canonical = await realpath(directory2);
+      const repoRoot = await checked(canonical, ["rev-parse", "--show-toplevel"]);
+      const branch = await run(canonical, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+      const remote = await run(canonical, ["config", "--get", "remote.origin.url"]);
+      const status = await checked(canonical, ["status", "--porcelain=v1", "--untracked-files=all"]);
+      return {
+        isGit: (
+          /** @type {const} */
+          true
+        ),
+        repoRoot,
+        currentBranch: branch.code === 0 ? branch.stdout.trim() : null,
+        remoteUrl: remote.code === 0 ? remote.stdout.trim() || null : null,
+        isDirty: !!status
+      };
+    },
+    async create(source, parent, name, branch, head) {
+      await directory(parent);
+      if (!/^wks_[0-9a-f]{16}$/.test(name) || branch !== `alp/workspace/${name}` || !/^[0-9a-f]{40,64}$/.test(head))
+        throw new Error("Invalid generated worktree identity");
+      const target = path.join(parent, name);
+      if (await lstat(target).catch((error) => {
+        if (error.code === "ENOENT") return void 0;
+        throw error;
+      }))
+        throw new Error("Worktree destination already exists");
+      await checked(source, ["worktree", "add", "--quiet", "--no-checkout", "-b", branch, target, head]);
+      await checked(target, ["reset", "--hard", "--no-recurse-submodules", head]);
+      if (!await inspect(source, target, branch)) throw new Error("Worktree creation needs reconciliation");
+      return target;
+    },
+    async remove(source, target, branch) {
+      if (!await inspect(source, target, branch)) throw new Error("Managed worktree is missing");
+      await assertClean(target);
+      await checked(source, ["worktree", "remove", target], await filterOverrides(target));
+      if ((await list(source)).some((row) => row.worktree === target))
+        throw new Error("Worktree removal needs reconciliation");
+    }
+  };
+}
+export {
+  repositoryIdentity,
+  userWorktreeGit
+};

package/packages/core/dist/validation.js

@@ -147,8 +147,9 @@ function validateUserSettings(settings, source) {
   }
   if (settings.web !== void 0) {
     check(object(settings.web), "web must be an object");
-    const extra = Object.keys(settings.web).find((field) => !["enabled", "port", "relay"].includes(field));
-    check(!extra, `unsupported web field '${extra}'; use enabled, port or relay`);
+    const extra = Object.keys(settings.web).find((field) => !["enabled", "port", "relay", "permissions"].includes(field));
+    check(!extra, `unsupported web field '${extra}'; use enabled, port, relay or permissions`);
+    if (settings.web.permissions !== void 0) check(Array.isArray(settings.web.permissions) && settings.web.permissions.every((entry) => typeof entry === "string" && /^[a-z][a-z.]*$/.test(entry)), "web.permissions must be a list of permission names, such as files.read");
     const relay = settings.web.relay;
     if (relay !== void 0) {
       check(object(relay), "web.relay must be an object");