djournal 0.1.0 → 0.2.0

package/lib/installer/index.js

@@ -1,14 +1,16 @@
 "use strict";
 
 const crypto = require("node:crypto");
+const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
+const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline/promises");
 const {
   equal,
   hasManagedBlock,
-  mergeHookConfig,
-  removeHookConfig,
+  mergeConfigFragment,
+  removeConfigFragment,
   removeManagedBlock,
   upsertManagedBlock,
 } = require("./merge.js");
@@ -18,6 +20,7 @@ const SUPPORTED_HARNESSES = ["codex", "claude-code"];
 const FUTURE_HARNESSES = ["opencode", "pi", "zed"];
 const MANIFEST_PATH = ".journal/.install/manifest.json";
 const TRANSACTION_PATH = ".journal/.install/transaction.json";
+const PROJECT_MARKER_PATH = ".djournal.json";
 
 class InstallerError extends Error {
   constructor(message, code = "INSTALL_ERROR") {
@@ -43,10 +46,163 @@ function parseJson(buffer, label) {
   catch (error) { throw new InstallerError(`${label} is not valid JSON: ${error.message}`, "INVALID_JSON"); }
 }
 
+function parseFrontmatter(text) {
+  if (!text.startsWith("---\n")) return {};
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) return {};
+  const result = {};
+  for (const line of text.slice(4, end).split("\n")) {
+    const match = line.match(/^([A-Za-z][A-Za-z0-9]*):\s*(.*)$/);
+    if (!match) continue;
+    result[match[1]] = match[2].trim().replace(/^"(.*)"$/, "$1");
+  }
+  return result;
+}
+
+function stringifyFrontmatterValue(value) {
+  return /[:#{}\[\],"]|\s/.test(value) ? JSON.stringify(value) : value;
+}
+
+function replaceFrontmatterField(text, field, value) {
+  if (!text.startsWith("---\n")) throw new InstallerError("work.md is missing frontmatter", "INVALID_JOURNAL");
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) throw new InstallerError("work.md has unterminated frontmatter", "INVALID_JOURNAL");
+  const before = text.slice(0, end);
+  const after = text.slice(end);
+  const line = `${field}: ${stringifyFrontmatterValue(value)}`;
+  const pattern = new RegExp(`^${field}:.*$`, "m");
+  const next = pattern.test(before) ? before.replace(pattern, line) : `${before}\n${line}`;
+  return `${next}${after}`;
+}
+
 function jsonBuffer(value) {
   return Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
 }
 
+function readJsonFile(file, label) {
+  return parseJson(readOptional(file), label);
+}
+
+function writeJsonFile(file, value) {
+  atomicWrite(file, jsonBuffer(value));
+}
+
+function mergePlainObject(base, patch) {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && result[key] && typeof result[key] === "object" && !Array.isArray(result[key])) {
+      result[key] = mergePlainObject(result[key], value);
+    } else result[key] = value;
+  }
+  return result;
+}
+
+function djournalHome(options = {}) {
+  return path.resolve(options.djournalHome || process.env.DJOURNAL_HOME || path.join(os.homedir(), ".djournal"));
+}
+
+function projectKeyFor(target) {
+  const base = path.basename(path.resolve(target)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "project";
+  return `${base}-${sha256(path.resolve(target)).slice(0, 8)}`;
+}
+
+function projectStoreFor(target, options = {}) {
+  const projectKey = options.projectKey || projectKeyFor(target);
+  const root = path.join(djournalHome(options), "projects", projectKey);
+  return { projectKey, root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, "config.json") };
+}
+
+function resolveProjectStore(target, options = {}) {
+  return readProjectMarker(target) || projectStoreFor(target, options);
+}
+
+function readProjectMarker(target) {
+  const marker = readOptional(resolveWithin(target, PROJECT_MARKER_PATH));
+  if (!marker) return null;
+  const value = parseJson(marker, PROJECT_MARKER_PATH);
+  if (value.schemaVersion !== SCHEMA_VERSION) {
+    throw new InstallerError(`unsupported project marker schema: ${value.schemaVersion}`, "UNSUPPORTED_MARKER");
+  }
+  if (!value.projectKey || !value.journalStore) {
+    throw new InstallerError("project marker is missing projectKey or journalStore", "INVALID_JSON");
+  }
+  const root = path.resolve(value.journalStore);
+  return { projectKey: value.projectKey, root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, "config.json") };
+}
+
+function projectContext(target, options = {}) {
+  const marker = readProjectMarker(target);
+  if (marker) return { ...marker, target, global: true };
+  const store = projectStoreFor(target, options);
+  if (fs.existsSync(store.configFile) || fs.existsSync(store.journalRoot)) return { ...store, target, global: true };
+  return {
+    target,
+    global: false,
+    projectKey: null,
+    root: target,
+    journalRoot: resolveWithin(target, ".journal"),
+    configFile: resolveWithin(target, ".journal/config.json"),
+  };
+}
+
+function defaultProjectConfig(target, store) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    project: {
+      id: store.projectKey,
+      name: path.basename(target),
+      sourcePath: path.resolve(target),
+    },
+    sync: {
+      enabled: false,
+      mode: "colocated",
+      path: path.resolve(target),
+      auto: false,
+    },
+    sharing: {
+      default: "local_only",
+      sharedWorkItems: {},
+    },
+  };
+}
+
+function readProjectConfig(context) {
+  const config = readJsonFile(context.configFile, context.global ? "config.json" : ".journal/config.json");
+  if (!context.global) return config;
+  return mergePlainObject(defaultProjectConfig(context.target, context), config);
+}
+
+function writeProjectConfig(context, config) {
+  if (!context.global) writeJsonFile(context.configFile, config);
+  else writeJsonFile(context.configFile, config);
+}
+
+function copyDirectoryContents(source, destination, options = {}) {
+  if (!fs.existsSync(source)) return [];
+  if (fs.lstatSync(source).isSymbolicLink()) throw new InstallerError(`source is a symlink: ${source}`, "UNSAFE_PATH");
+  const copied = [];
+  for (const relative of listFiles(source)) {
+    if (options.exclude?.(relative)) continue;
+    const sourceFile = path.join(source, relative);
+    const destinationFile = path.join(destination, relative);
+    const destinationRoot = path.resolve(destination);
+    const resolved = path.resolve(destinationFile);
+    if (resolved !== destinationRoot && !resolved.startsWith(`${destinationRoot}${path.sep}`)) {
+      throw new InstallerError(`projection escapes target: ${relative}`, "UNSAFE_PATH");
+    }
+    if (fs.lstatSync(sourceFile).isSymbolicLink()) throw new InstallerError(`source file is a symlink: ${relative}`, "UNSAFE_PATH");
+    if (fs.existsSync(destinationFile) && fs.lstatSync(destinationFile).isSymbolicLink()) {
+      throw new InstallerError(`projection destination is a symlink: ${relative}`, "UNSAFE_PATH");
+    }
+    if (!options.dryRun) {
+      fs.mkdirSync(path.dirname(destinationFile), { recursive: true });
+      fs.copyFileSync(sourceFile, destinationFile);
+    }
+    copied.push(relative.split(path.sep).join("/"));
+  }
+  return copied;
+}
+
 function resolveWithin(target, relative) {
   if (!relative || path.isAbsolute(relative)) {
     throw new InstallerError(`unsafe destination path: ${relative}`, "UNSAFE_PATH");
@@ -82,7 +238,7 @@ function listFiles(directory, prefix = "") {
 }
 
 function sourceInventory(sourceRoot) {
-  const files = ["spec.md"];
+  const files = [];
   for (const directory of [".agents/rules", ".agents/skills", ".agents/adapters"]) {
     for (const relative of listFiles(path.join(sourceRoot, directory))) {
       files.push(`${directory}/${relative}`);
@@ -252,21 +408,36 @@ function markdownRecord(target, relative, body, oldRecord, harness) {
   };
 }
 
+function journalAccessFragment(harness, store) {
+  if (harness !== "claude-code") return {};
+  const commands = ["status", "doctor", "config", "share", "sync"];
+  return {
+    permissions: {
+      additionalDirectories: [store.root],
+      allow: commands.flatMap((command) => [
+        `Bash(journal ${command}:*)`,
+        `Bash(djournal ${command}:*)`,
+      ]),
+    },
+  };
+}
+
 function jsonRecord(target, relative, fragment, oldRecord, harness) {
   const absolute = resolveWithin(target, relative);
   const original = readOptional(absolute);
   const current = parseJson(original, relative);
   let base = current;
-  if (oldRecord?.injected) {
-    const removed = removeHookConfig(base, oldRecord.injected);
+  if (oldRecord?.injected || oldRecord?.injectedPermissions) {
+    const removed = removeConfigFragment(base, oldRecord.injected, oldRecord.injectedPermissions);
     if (removed.conflicts.length) {
-      throw new InstallerError(`managed hook group was modified: ${relative}`, "ASSET_CONFLICT");
+      throw new InstallerError(`managed JSON fragment was modified: ${relative}`, "ASSET_CONFLICT");
     }
     base = removed.value;
   }
-  const merged = mergeHookConfig(base, fragment);
+  const merged = mergeConfigFragment(base, fragment);
   const injectedCount = Object.values(merged.injected).reduce((total, groups) => total + groups.length, 0);
-  const next = injectedCount === 0 && original !== null ? original : jsonBuffer(merged.value);
+  const injectedPermissionCount = Object.values(merged.injectedPermissions).reduce((total, values) => total + values.length, 0);
+  const next = injectedCount === 0 && injectedPermissionCount === 0 && original !== null ? original : jsonBuffer(merged.value);
   return {
     op: operation(target, relative, next),
     record: {
@@ -276,6 +447,7 @@ function jsonRecord(target, relative, fragment, oldRecord, harness) {
       created: oldRecord?.created ?? original === null,
       installedHash: sha256(next),
       injected: merged.injected,
+      injectedPermissions: merged.injectedPermissions,
     },
   };
 }
@@ -307,7 +479,7 @@ function harnessFragment(sourceRoot, harness) {
   return parseJson(fs.readFileSync(path.join(sourceRoot, relative)), relative);
 }
 
-function planInstall(sourceRoot, target, harnesses, oldManifest) {
+function planInstall(sourceRoot, target, harnesses, oldManifest, store) {
   const old = recordMap(oldManifest);
   const records = [];
   const operations = [];
@@ -326,7 +498,13 @@ function planInstall(sourceRoot, target, harnesses, oldManifest) {
   if (harnesses.includes("claude-code")) {
     const bridge = markdownRecord(target, "CLAUDE.md", "@AGENTS.md", old.get("CLAUDE.md"), "claude-code");
     records.push(bridge.record); operations.push(bridge.op);
-    const hooks = jsonRecord(target, ".claude/settings.json", harnessFragment(sourceRoot, "claude-code"), old.get(".claude/settings.json"), "claude-code");
+    const hooks = jsonRecord(
+      target,
+      ".claude/settings.json",
+      mergePlainObject(harnessFragment(sourceRoot, "claude-code"), journalAccessFragment("claude-code", store)),
+      old.get(".claude/settings.json"),
+      "claude-code",
+    );
     records.push(hooks.record); operations.push(hooks.op);
   }
 
@@ -356,6 +534,258 @@ function checkTarget(target) {
   return resolved;
 }
 
+function readActiveWork(context, requested) {
+  const journalRoot = context.journalRoot;
+  let slug = requested;
+  if (!slug) {
+    const state = parseJson(readOptional(path.join(journalRoot, "state.json")), ".journal/state.json");
+    slug = state.active_work_name;
+  }
+  if (typeof slug !== "string" || !slug) {
+    throw new InstallerError("No active work found. Run init-work or switch first.", "NO_ACTIVE_WORK");
+  }
+  if (slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") {
+    throw new InstallerError(`invalid work slug: ${slug}`, "INVALID_WORK");
+  }
+  const relative = `.journal/work/${slug}/work.md`;
+  const file = path.join(journalRoot, "work", slug, "work.md");
+  const buffer = readOptional(file);
+  if (!buffer) throw new InstallerError(`work item not found: ${slug}`, "INVALID_WORK");
+  const text = buffer.toString("utf8");
+  const metadata = parseFrontmatter(text);
+  return { slug, relative, file, text, metadata, visibility: metadata.visibility || "local_only" };
+}
+
+function readJournalConfig(target) {
+  const context = projectContext(target);
+  return readProjectConfig(context);
+}
+
+function syncConfig(target) {
+  const config = readJournalConfig(target);
+  return config.sync && typeof config.sync === "object" ? config.sync : {};
+}
+
+function sharingConfig(config) {
+  return config.sharing && typeof config.sharing === "object" ? config.sharing : {};
+}
+
+function sharedWorkItems(config) {
+  const sharing = sharingConfig(config);
+  return sharing.sharedWorkItems && typeof sharing.sharedWorkItems === "object" ? sharing.sharedWorkItems : {};
+}
+
+function isWorkShared(config, slug) {
+  return Object.prototype.hasOwnProperty.call(sharedWorkItems(config), slug);
+}
+
+function parseConfigValue(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  return value;
+}
+
+function setNested(value, keyPath, next) {
+  const parts = keyPath.split(".").filter(Boolean);
+  if (!parts.length) throw new InstallerError("config key is required", "USAGE");
+  const result = { ...value };
+  let cursor = result;
+  for (const part of parts.slice(0, -1)) {
+    const current = cursor[part];
+    cursor[part] = current && typeof current === "object" && !Array.isArray(current) ? { ...current } : {};
+    cursor = cursor[part];
+  }
+  cursor[parts.at(-1)] = next;
+  return result;
+}
+
+function getNested(value, keyPath) {
+  if (!keyPath) return value;
+  let cursor = value;
+  for (const part of keyPath.split(".").filter(Boolean)) {
+    if (!cursor || typeof cursor !== "object" || !(part in cursor)) return undefined;
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+
+function configure(options) {
+  const target = checkTarget(options.target || process.cwd());
+  const context = projectContext(target, options);
+  if (!context.global) throw new InstallerError("djournal project store is not initialized; run journal install first", "NOT_INSTALLED");
+  const current = readProjectConfig(context);
+  if (!options.key) return { action: "config", target, projectKey: context.projectKey, config: current };
+  if (typeof options.value === "undefined") {
+    return { action: "config", target, projectKey: context.projectKey, key: options.key, value: getNested(current, options.key) };
+  }
+  const next = setNested(current, options.key, parseConfigValue(options.value));
+  if (!options.dryRun) writeProjectConfig(context, next);
+  return { action: "config", target, projectKey: context.projectKey, key: options.key, value: getNested(next, options.key), changed: true, dryRun: !!options.dryRun };
+}
+
+function gitIgnored(target, relative, options = {}) {
+  const result = (options.runner || spawnSync)("git", ["-C", target, "check-ignore", "-q", relative], {
+    encoding: "utf8",
+    timeout: options.timeout || 30000,
+  });
+  if (result.error) return false;
+  return result.status === 0;
+}
+
+function share(options) {
+  const target = checkTarget(options.target || process.cwd());
+  const context = projectContext(target, options);
+  const config = readProjectConfig(context);
+  const work = readActiveWork(context, options.work);
+  const projectionRoot = projectionRootFor(target, config);
+  const ignored = config.sync?.mode === "colocated" ? gitIgnored(projectionRoot, `.journal/work/${work.slug}`, options) : false;
+  const warning = ignored
+    ? `.journal/work/${work.slug} appears to be ignored by Git; update .gitignore or force-add it before expecting colocated Git commits to share this work.`
+    : undefined;
+  const shared = sharedWorkItems(config);
+  if (Object.prototype.hasOwnProperty.call(shared, work.slug)) {
+    return { action: "share", target, projectKey: context.projectKey, work: work.slug, changed: false, shared: true, gitIgnored: ignored, warning };
+  }
+  const next = mergePlainObject(config, {
+    sharing: {
+      sharedWorkItems: {
+        ...shared,
+        [work.slug]: {
+          sharedAt: new Date().toISOString(),
+          sharedBy: process.env.JOURNAL_USER_ID || runGitConfigEmail(options) || `${os.userInfo().username}@local`,
+        },
+      },
+    },
+  });
+  if (!options.dryRun) writeProjectConfig(context, next);
+  return { action: "share", target, projectKey: context.projectKey, work: work.slug, changed: true, shared: true, dryRun: !!options.dryRun, gitIgnored: ignored, warning };
+}
+
+function runGitConfigEmail(options = {}) {
+  const result = (options.runner || spawnSync)("git", ["config", "user.email"], {
+    encoding: "utf8",
+    timeout: options.timeout || 30000,
+  });
+  if (result.error || result.status !== 0) return "";
+  return (result.stdout || "").trim();
+}
+
+function runGit(gitRoot, args, options = {}) {
+  const result = (options.runner || spawnSync)("git", ["-C", gitRoot, ...args], {
+    encoding: "utf8",
+    timeout: options.timeout || 30000,
+  });
+  if (result.error) throw new InstallerError(result.error.message, "GIT_ERROR");
+  if (result.status !== 0) {
+    const detail = `${result.stderr || ""}${result.stdout || ""}`.trim();
+    throw new InstallerError(detail || `git ${args.join(" ")} failed`, "GIT_ERROR");
+  }
+  return (result.stdout || "").trim();
+}
+
+function gitRootFor(directory, options = {}) {
+  const result = (options.runner || spawnSync)("git", ["-C", directory, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    timeout: options.timeout || 30000,
+  });
+  if (result.error) throw new InstallerError(result.error.message, "GIT_ERROR");
+  if (result.status !== 0) throw new InstallerError(".journal is not inside a Git work tree", "GIT_ERROR");
+  return (result.stdout || "").trim();
+}
+
+function journalPathspec(gitRoot, journalRoot) {
+  const relative = path.relative(gitRoot, journalRoot).split(path.sep).join("/");
+  return relative && !relative.startsWith("..") ? relative : ".";
+}
+
+function projectionRootFor(target, config) {
+  const sync = config.sync && typeof config.sync === "object" ? config.sync : {};
+  if (sync.path) return path.resolve(target, sync.path);
+  return path.resolve(target);
+}
+
+function projectJournalRoot(projectionRoot) {
+  return path.join(projectionRoot, ".journal");
+}
+
+function projectSharedWork(context, config, work, options = {}) {
+  const targetRoot = projectionRootFor(context.target, config);
+  const destinationJournal = projectJournalRoot(targetRoot);
+  const sourceWork = path.join(context.journalRoot, "work", work.slug);
+  const destinationWork = path.join(destinationJournal, "work", work.slug);
+  if (!fs.existsSync(sourceWork)) throw new InstallerError(`work item not found: ${work.slug}`, "INVALID_WORK");
+  const files = copyDirectoryContents(sourceWork, destinationWork, options).map((file) => `.journal/work/${work.slug}/${file}`);
+  return { projectionRoot: targetRoot, journalRoot: destinationJournal, files };
+}
+
+function bootstrapProjectStore(target, options = {}) {
+  const store = options.store || resolveProjectStore(target, options);
+  const existingConfig = readOptional(store.configFile);
+  const config = existingConfig
+    ? mergePlainObject(defaultProjectConfig(target, store), parseJson(existingConfig, "config.json"))
+    : defaultProjectConfig(target, store);
+  const legacyConfig = readOptional(resolveWithin(target, ".journal/config.json"));
+  if (legacyConfig) {
+    const parsedLegacy = parseJson(legacyConfig, ".journal/config.json");
+    if (parsedLegacy.sync || parsedLegacy.sharing) {
+      config.sync = { ...config.sync, ...(parsedLegacy.sync || {}) };
+      config.sharing = mergePlainObject(config.sharing, parsedLegacy.sharing || {});
+    }
+  }
+  if (!options.dryRun) {
+    fs.mkdirSync(store.journalRoot, { recursive: true });
+    copyDirectoryContents(resolveWithin(target, ".journal"), store.journalRoot, {
+      dryRun: false,
+      exclude: (relative) => relative === "config.json" || relative.startsWith(".install/"),
+    });
+    writeProjectConfig({ ...store, target, global: true }, config);
+  }
+  return { ...store, config };
+}
+
+function sync(options) {
+  const target = checkTarget(options.target || process.cwd());
+  const context = projectContext(target, options);
+  const config = readProjectConfig(context);
+  const syncOptions = config.sync && typeof config.sync === "object" ? config.sync : {};
+  if (syncOptions.enabled !== true) {
+    return { action: "sync", target, skipped: true, reason: "sync is not enabled" };
+  }
+  if (!["colocated", "standalone"].includes(syncOptions.mode)) {
+    return { action: "sync", target, skipped: true, reason: "sync mode is not standalone" };
+  }
+  const work = readActiveWork(context, options.work);
+  if (!isWorkShared(config, work.slug)) {
+    return { action: "sync", target, work: work.slug, skipped: true, reason: "work is not shared" };
+  }
+  const projection = projectSharedWork(context, config, work, options);
+  if (syncOptions.mode === "colocated") {
+    return { action: "sync", target, work: work.slug, projectionRoot: projection.projectionRoot, files: projection.files, dryRun: !!options.dryRun };
+  }
+  const gitRoot = gitRootFor(projection.journalRoot, options);
+  const pathspec = journalPathspec(gitRoot, projection.journalRoot);
+  const unmerged = runGit(gitRoot, ["diff", "--name-only", "--diff-filter=U", "--", pathspec], options);
+  if (unmerged) throw new InstallerError(`unresolved journal conflicts:\n${unmerged}`, "SYNC_CONFLICT");
+  if (options.dryRun) return { action: "sync", target, work: work.slug, projectionRoot: projection.projectionRoot, gitRoot, pathspec, files: projection.files, dryRun: true };
+
+  runGit(gitRoot, ["pull", "--ff-only"], options);
+  const afterPullUnmerged = runGit(gitRoot, ["diff", "--name-only", "--diff-filter=U", "--", pathspec], options);
+  if (afterPullUnmerged) throw new InstallerError(`unresolved journal conflicts:\n${afterPullUnmerged}`, "SYNC_CONFLICT");
+  runGit(gitRoot, ["add", "--", pathspec], options);
+  let committed = true;
+  try {
+    runGit(gitRoot, ["diff", "--cached", "--quiet", "--", pathspec], options);
+    committed = false;
+  } catch (error) {
+    if (!(error instanceof InstallerError) || error.code !== "GIT_ERROR") throw error;
+    runGit(gitRoot, ["commit", "-m", `chore(journal): sync ${work.slug}`], options);
+  }
+  runGit(gitRoot, ["push"], options);
+  return { action: "sync", target, work: work.slug, projectionRoot: projection.projectionRoot, gitRoot, pathspec, files: projection.files, committed, pushed: true, auto: !!options.auto };
+}
+
 function doctor(options) {
   const target = checkTarget(options.target || process.cwd());
   const detected = detectHarnesses(target, options);
@@ -389,7 +819,8 @@ async function install(options) {
   const detected = health.detected;
   const selected = await selectHarnesses({ ...options, interactive: options.interactive ?? process.stdin.isTTY }, detected);
   const harnesses = [...new Set([...(oldManifest?.harnesses || []), ...selected])].sort();
-  const planned = planInstall(sourceRoot, target, harnesses, oldManifest);
+  const store = bootstrapProjectStore(target, { ...options, store: resolveProjectStore(target, options) });
+  const planned = planInstall(sourceRoot, target, harnesses, oldManifest, store);
   const manifest = {
     schemaVersion: SCHEMA_VERSION,
     toolVersion: packageVersion(sourceRoot),
@@ -398,6 +829,11 @@ async function install(options) {
     harnesses,
     files: planned.records.sort((a, b) => a.path.localeCompare(b.path)),
   };
+  planned.operations.push(operation(target, PROJECT_MARKER_PATH, jsonBuffer({
+    schemaVersion: SCHEMA_VERSION,
+    projectKey: store.projectKey,
+    journalStore: store.root,
+  })));
   planned.operations.push(operation(target, MANIFEST_PATH, jsonBuffer(manifest)));
   applyTransaction(target, planned.operations, options);
   if (!options.dryRun) {
@@ -440,7 +876,7 @@ function uninstallRecord(target, record, conflicts) {
     const injectedCount = Object.values(record.injected || {}).reduce((total, groups) => total + groups.length, 0);
     if (injectedCount === 0 && !record.created) return null;
     const parsed = parseJson(current, record.path);
-    const removed = removeHookConfig(parsed, record.injected);
+    const removed = removeConfigFragment(parsed, record.injected, record.injectedPermissions);
     if (removed.conflicts.length) { conflicts.push(record.path); return null; }
     const empty = Object.keys(removed.value).length === 0;
     return operation(target, record.path, empty && record.created ? null : jsonBuffer(removed.value));
@@ -504,8 +940,11 @@ function recordStatus(target, record) {
   if (record.mode === "json_merge") {
     try {
       const value = parseJson(current, record.path);
-      const present = Object.entries(record.injected || {}).every(([event, groups]) =>
+      const hooksPresent = Object.entries(record.injected || {}).every(([event, groups]) =>
         groups.every((group) => value.hooks?.[event]?.some((candidate) => equal(candidate, group))));
+      const permissionsPresent = Object.entries(record.injectedPermissions || {}).every(([key, values]) =>
+        values.every((item) => value.permissions?.[key]?.some((candidate) => equal(candidate, item))));
+      const present = hooksPresent && permissionsPresent;
       return present ? (sha256(current) === record.installedHash ? "clean" : "modified") : "missing";
     } catch { return "invalid"; }
   }
@@ -523,15 +962,21 @@ function status(options) {
 module.exports = {
   InstallerError,
   MANIFEST_PATH,
+  PROJECT_MARKER_PATH,
   SUPPORTED_HARNESSES,
   applyTransaction,
+  configure,
   detectHarnesses,
   doctor,
+  djournalHome,
   install,
   loadManifest,
+  projectContext,
   recoverTransaction,
   selectHarnesses,
+  share,
   sourceInventory,
+  sync,
   status,
   uninstall,
   upgrade,

package/lib/installer/merge.js

@@ -90,6 +90,47 @@ function mergeHookConfig(current, fragment) {
   return { value: next, injected };
 }
 
+function appendUnique(target, values) {
+  const injected = [];
+  for (const value of values || []) {
+    if (!target.some((candidate) => equal(candidate, value))) {
+      const copy = structuredClone(value);
+      target.push(copy);
+      injected.push(copy);
+    }
+  }
+  return injected;
+}
+
+function mergePermissionsConfig(current, fragment) {
+  const next = structuredClone(current);
+  const permissions = fragment.permissions || {};
+  const injected = {};
+  if (Array.isArray(permissions.additionalDirectories)) {
+    next.permissions ||= {};
+    next.permissions.additionalDirectories ||= [];
+    const additions = appendUnique(next.permissions.additionalDirectories, permissions.additionalDirectories);
+    if (additions.length) injected.additionalDirectories = additions;
+  }
+  if (Array.isArray(permissions.allow)) {
+    next.permissions ||= {};
+    next.permissions.allow ||= [];
+    const additions = appendUnique(next.permissions.allow, permissions.allow);
+    if (additions.length) injected.allow = additions;
+  }
+  return { value: next, injected };
+}
+
+function mergeConfigFragment(current, fragment) {
+  const hook = mergeHookConfig(current, fragment);
+  const permissions = mergePermissionsConfig(hook.value, fragment);
+  return {
+    value: permissions.value,
+    injected: hook.injected,
+    injectedPermissions: permissions.injected,
+  };
+}
+
 function removeHookConfig(current, injected) {
   const next = structuredClone(current);
   const conflicts = [];
@@ -110,6 +151,35 @@ function removeHookConfig(current, injected) {
   return { value: next, conflicts };
 }
 
+function removePermissionsConfig(current, injected) {
+  const next = structuredClone(current);
+  const conflicts = [];
+  for (const [key, values] of Object.entries(injected || {})) {
+    const existing = next.permissions?.[key];
+    if (!Array.isArray(existing)) {
+      conflicts.push(`permissions.${key}`);
+      continue;
+    }
+    for (const value of values) {
+      const index = existing.findIndex((candidate) => equal(candidate, value));
+      if (index === -1) conflicts.push(`permissions.${key}`);
+      else existing.splice(index, 1);
+    }
+    if (existing.length === 0) delete next.permissions[key];
+  }
+  if (next.permissions && Object.keys(next.permissions).length === 0) delete next.permissions;
+  return { value: next, conflicts };
+}
+
+function removeConfigFragment(current, injected, injectedPermissions) {
+  const hook = removeHookConfig(current, injected);
+  const permissions = removePermissionsConfig(hook.value, injectedPermissions);
+  return {
+    value: permissions.value,
+    conflicts: [...hook.conflicts, ...permissions.conflicts],
+  };
+}
+
 module.exports = {
   BEGIN,
   END,
@@ -118,8 +188,12 @@ module.exports = {
   equal,
   hasManagedBlock,
   managedBlock,
+  mergeConfigFragment,
   mergeHookConfig,
+  mergePermissionsConfig,
+  removeConfigFragment,
   removeHookConfig,
+  removePermissionsConfig,
   removeManagedBlock,
   upsertManagedBlock,
 };