@vantran-se/openchamber-web 1.22.1 → 1.23.0

package/server/lib/projects/DOCUMENTATION.md

@@ -0,0 +1,76 @@
+# Projects
+
+## Purpose
+
+Server-owned storage for a project's per-user config file,
+`~/.config/openchamber/projects/<projectId>.json`. The file holds two
+families of keys with different writers, and this module is the only place
+that writes it:
+
+| Keys | Owner | Reached through |
+|---|---|---|
+| `version`, `scheduledTasks` | `project-config.js` (scheduled-task runtime) | `/api/projects/:projectId/scheduled-tasks/*` |
+| `setup-worktree`, `setup-worktree-wait`, `projectActions`, `projectActionsPrimaryId`, `draftStarters`, `projectPath` | `project-setup.js` via `readProjectSetup` / `updateProjectSetup` on the same runtime | `GET/PUT /api/projects/:projectId/config` (`routes.js`) |
+
+Notes, todos, and plans moved out of this file to `packages/web/server/lib/project-context`.
+
+A second, optional source is the team's shared file, `<repo>/.openchamber/project.json`
+(`version: 1`; `setupWorktree`, `setupWorktreeWait`, `projectActions`, `draftStarters`,
+`plansDir`). The server reads it from the checkout the project id names
+(`projectPathFromId`). `GET /api/projects/:projectId/config`
+returns one merged view: what runs at the top level, plus `shared` and `personal`
+blocks so a page can edit the personal file without copying a teammate's entry into it.
+
+| Field | Merge rule |
+|---|---|
+| `setupWorktree` | shared first, then personal; personal `setupWorktreeMode: "replace"` uses the personal list only |
+| `setupWorktreeWait` | personal when the personal file sets it, else shared, else `false` |
+| `projectActions` | union by `id`; a personal action replaces the shared one with the same id; ids in personal `hiddenSharedActionIds` are dropped; every entry carries `source` |
+| `projectActionsPrimaryId` | personal only |
+| `draftStarters` | union by `type:name`, shared first, every entry carries `source` |
+| `plansDir` | shared only |
+
+A shared file that exists but cannot be parsed (or names a `plansDir` outside the
+repo) is `shared.status: "invalid"` with a `reason`; the personal setup is still
+served. It is never treated as "no shared setup".
+
+### Writing the shared file
+
+`PUT /api/projects/:projectId/config/shared` (`updateSharedProjectSetup`) is
+the only writer. The patch replaces the keys it names over the current file
+(a broken file counts as empty, so a write repairs it); the result is written
+pretty-printed with `version` first and only the keys that carry something
+(`serializeSharedProjectConfig`), because the file is committed and reviewed.
+A result with nothing in it removes the file and the `.openchamber` folder
+when that leaves it empty, so unsharing the last item leaves no trace. The
+write refuses a checkout that does not exist and a `plansDir` outside the
+repo. The writer has seen what it shared, so its personal trust record is set
+to the new hash; teammates still get the prompt. The shared UI composes
+"share" and "make personal" as a shared write followed by a personal write.
+
+### Trust
+
+Shared setup commands and shared actions run on the machine of whoever pulls
+the repo, so they run only after the user has seen them. The view carries
+`trust: { hash, trusted }`: `hash` is `sharedTrustHashOf(shared)`, a SHA-256
+over the executable parts (`setupWorktree` and each action's `id`, `command`,
+`runIn`, actions sorted by id; names and icons do not count), or `null` when
+nothing executes. `trusted` is true when nothing executes or the personal
+file's `sharedTrust.hash` equals the current hash, so a pull that changes a
+command brings the prompt back. The client records an answer with a PUT of
+`sharedTrustHash` (`null` forgets it). The prompt itself lives in the shared
+UI (`packages/ui/src/lib/sharedTrustConfirmation.ts`).
+
+## Modules
+
+- `project-id.js` — `createProjectIdFromPath` / `projectPathFromId`: the path-derived id (`path_<base64url>`) that names the file, and the checkout path back from it. The shared UI derives the same id (`packages/ui/src/lib/projectId.ts`); both sides must agree.
+- `project-config.js` — `createProjectConfigRuntime`: raw read, atomic write, the cross-process file lock (Electron and a CLI `serve` can share one projects dir), scheduled-task normalization, and the project-setup read/update.
+- `project-setup.js` — sanitizers, the shared-file parser (`parseSharedProjectConfig`, `normalizePlansDir`), the merge (`mergeProjectSetup`), and the personal view for the setup keys. Mirrored in the VS Code extension host (`packages/vscode/src/project-setup.ts`), which owns the same file when the webview has no OpenChamber server; keep the two in sync.
+- `routes.js` — the setup routes. `/api/projects` is on the JSON-body allowlist in `opencode/core-routes.js`.
+
+## Invariants
+
+- **Every write is a locked read-modify-write of the whole document.** Keys the writer does not own, and keys from newer builds, come back out unchanged. A setup update and a scheduled-task update never clobber each other.
+- **A wrongly shaped key is a 400, not a silent drop.** `projectSetupPatchToStored` throws; the file is untouched. Values inside a well-shaped key are sanitized (trimmed, capped, deduplicated) rather than rejected.
+- **The client never composes the path.** `packages/ui/src/lib/openchamberConfig.ts` speaks only HTTP; the same code serves web, desktop, VS Code, and the phone, including a phone on a remote instance.
+- **`OPENCHAMBER_DATA_DIR` moves this directory too.** Every OpenChamber folder hangs off the one root; a custom root gets `projects/`, `themes/`, and `speech-models/` copied in from `~/.config/openchamber` once at startup (copied, not moved: a second instance beside the default one must not strip it) (`lib/data-dir-migration.js`). A scratch server started with its own data dir therefore never touches the real project configs.

package/server/lib/projects/project-config.js

@@ -1,6 +1,21 @@
 import { DateTime, IANAZone } from 'luxon';
 import parser from 'cron-parser';
 
+import { projectPathFromId } from './project-id.js';
+import {
+  DEFAULT_PLANS_DIR,
+  EMPTY_SHARED_PROJECT_CONFIG,
+  SHARED_CONFIG_RELATIVE_PATH,
+  applySharedProjectSetupPatch,
+  isSharedProjectConfigEmpty,
+  mergeProjectSetup,
+  parseSharedProjectConfig,
+  projectSetupPatchToStored,
+  projectSetupViewOf,
+  serializeSharedProjectConfig,
+  sharedTrustHashOf,
+} from './project-setup.js';
+
 const PROJECT_CONFIG_VERSION = 1;
 export const MAX_TASK_NAME_LENGTH = 80;
 const MAX_TASK_PROMPT_LENGTH = 20_000;
@@ -548,21 +563,16 @@ export const createProjectConfigRuntime = (deps) => {
     })
   );
 
-  const writeProjectConfigToDisk = async (projectID, config) => {
+  // Atomic whole-document write; callers hand in the merged document so the
+  // keys they do not own survive untouched.
+  const writeRawProjectConfigToDisk = async (projectID, document) => {
     const filePath = resolveProjectConfigPath(projectID);
     const parentDirectory = path.dirname(filePath);
     const temporaryPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 
-    const existing = await readRawProjectConfigFromDisk(projectID);
-    const merged = {
-      ...existing,
-      version: PROJECT_CONFIG_VERSION,
-      scheduledTasks: Array.isArray(config?.scheduledTasks) ? config.scheduledTasks : [],
-    };
-
     await fsPromises.mkdir(parentDirectory, { recursive: true });
     try {
-      await fsPromises.writeFile(temporaryPath, JSON.stringify(merged, null, 2), 'utf8');
+      await fsPromises.writeFile(temporaryPath, JSON.stringify(document, null, 2), 'utf8');
       await fsPromises.rename(temporaryPath, filePath);
     } catch (error) {
       await fsPromises.rm(temporaryPath, { force: true }).catch(() => {});
@@ -570,6 +580,15 @@ export const createProjectConfigRuntime = (deps) => {
     }
   };
 
+  const writeProjectConfigToDisk = async (projectID, config) => {
+    const existing = await readRawProjectConfigFromDisk(projectID);
+    await writeRawProjectConfigToDisk(projectID, {
+      ...existing,
+      version: PROJECT_CONFIG_VERSION,
+      scheduledTasks: Array.isArray(config?.scheduledTasks) ? config.scheduledTasks : [],
+    });
+  };
+
   const withProjectWriteLock = async (projectID, mutate) => {
     const key = sanitizeProjectID(projectID);
     const previous = writeLocks.get(key) || Promise.resolve();
@@ -905,7 +924,121 @@ export const createProjectConfigRuntime = (deps) => {
     });
   };
 
+  // The client-owned part of the file (worktree setup, project actions, draft
+  // starters); see `project-setup.js`. Reads are lock-free like task lists;
+  // an update merges the sanitized patch over the raw document under the same
+  // cross-process lock the task writers use, so neither side clobbers the other.
+  // The shared file lives in the project's checkout. The checkout path comes
+  // from the id itself (`path_<base64url>`), with the personal file's
+  // `projectPath` as the fallback for ids of another form. A missing file is
+  // the normal case; an unreadable or unparsable one is reported as invalid,
+  // never as "no shared setup".
+  const projectPathOf = (projectID, personalRaw) => (
+    projectPathFromId(projectID) || (typeof personalRaw.projectPath === 'string' ? personalRaw.projectPath.trim() : '')
+  );
+  const sharedConfigPathOf = (projectPath) => path.join(projectPath, ...SHARED_CONFIG_RELATIVE_PATH.split('/'));
+
+  const readSharedProjectConfig = async (projectID, personalRaw) => {
+    const projectPath = projectPathOf(projectID, personalRaw);
+    if (!projectPath) return { status: 'missing' };
+    let raw;
+    try {
+      raw = await fsPromises.readFile(sharedConfigPathOf(projectPath), 'utf8');
+    } catch (error) {
+      if (error && typeof error === 'object' && error.code === 'ENOENT') return { status: 'missing' };
+      return { status: 'invalid', reason: error instanceof Error ? error.message : String(error) };
+    }
+    return parseSharedProjectConfig(raw);
+  };
+
+  const mergedProjectSetupOf = async (projectID, personalRaw) => (
+    mergeProjectSetup(projectSetupViewOf(personalRaw), await readSharedProjectConfig(projectID, personalRaw))
+  );
+
+  const readProjectSetup = async (projectID) => mergedProjectSetupOf(projectID, await readRawProjectConfigFromDisk(projectID));
+
+  const updateProjectSetup = async (projectID, patch) => {
+    const stored = projectSetupPatchToStored(patch);
+    return withProjectWriteLock(projectID, async () => {
+      const existing = await readRawProjectConfigFromDisk(projectID);
+      const merged = { ...existing, ...stored };
+      for (const [key, value] of Object.entries(stored)) {
+        if (value === undefined) delete merged[key];
+      }
+      await writeRawProjectConfigToDisk(projectID, merged);
+      return mergedProjectSetupOf(projectID, merged);
+    });
+  };
+
+  /**
+   * Change the team's shared file in the checkout: the patch replaces the
+   * keys it names over the current file (a broken file counts as empty, so
+   * a write repairs it). A result with nothing in it removes the file (and
+   * the `.openchamber` folder when that leaves it empty), so unsharing the
+   * last item leaves no trace. The writer has seen the commands it just
+   * shared, so the personal trust record is set to the new hash on this
+   * instance; teammates still get the prompt.
+   */
+  const updateSharedProjectSetup = async (projectID, patch) => (
+    withProjectWriteLock(projectID, async () => {
+      const personalRaw = await readRawProjectConfigFromDisk(projectID);
+      const projectPath = projectPathOf(projectID, personalRaw);
+      if (!projectPath) throw new Error('project checkout not found');
+      try {
+        if (!(await fsPromises.stat(projectPath)).isDirectory()) throw new Error('project checkout not found');
+      } catch {
+        throw new Error('project checkout not found');
+      }
+      const currentRead = await readSharedProjectConfig(projectID, personalRaw);
+      const current = currentRead.status === 'ok' ? currentRead.config : EMPTY_SHARED_PROJECT_CONFIG;
+      const next = applySharedProjectSetupPatch(current, patch);
+
+      const filePath = sharedConfigPathOf(projectPath);
+      if (isSharedProjectConfigEmpty(next)) {
+        await fsPromises.rm(filePath, { force: true });
+        await fsPromises.rmdir(path.dirname(filePath)).catch(() => {});
+      } else {
+        await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+        const temporaryPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+        try {
+          await fsPromises.writeFile(temporaryPath, serializeSharedProjectConfig(next), 'utf8');
+          await fsPromises.rename(temporaryPath, filePath);
+        } catch (error) {
+          await fsPromises.rm(temporaryPath, { force: true }).catch(() => {});
+          throw error;
+        }
+      }
+
+      const hash = sharedTrustHashOf(next);
+      const personalNext = { ...personalRaw };
+      if (hash) personalNext.sharedTrust = { hash, trustedAt: Date.now() };
+      else delete personalNext.sharedTrust;
+      await writeRawProjectConfigToDisk(projectID, personalNext);
+      return mergedProjectSetupOf(projectID, personalNext);
+    })
+  );
+
+  /**
+   * The absolute repository plans folder of a project: `plansDir` from the
+   * shared file when set, else the default `.openchamber/plans`. Setting
+   * `plansDir` replaces the default outright (nothing is read from it any
+   * more); moving files between the two is the user's job. Null only when the
+   * checkout cannot be located.
+   */
+  const resolveSharedPlansDir = async (projectID) => {
+    const personalRaw = await readRawProjectConfigFromDisk(projectID);
+    const projectPath = projectPathOf(projectID, personalRaw);
+    if (!projectPath) return null;
+    const shared = await readSharedProjectConfig(projectID, personalRaw);
+    const relative = shared.status === 'ok' && shared.config.plansDir ? shared.config.plansDir : DEFAULT_PLANS_DIR;
+    return path.join(projectPath, ...relative.split('/'));
+  };
+
   return {
+    readProjectSetup,
+    updateProjectSetup,
+    updateSharedProjectSetup,
+    resolveSharedPlansDir,
     listScheduledTasks,
     upsertScheduledTask,
     deleteScheduledTask,

package/server/lib/projects/project-id.js

@@ -11,3 +11,20 @@ export const createProjectIdFromPath = (projectPath) => {
 
   return `path_${Buffer.from(normalized, 'utf8').toString('base64url')}`;
 };
+
+/**
+ * The path a `path_<base64url>` id was made from, or `''` when the id is not
+ * of that form. The projects dir names files by this id, so the server can
+ * find the project's checkout (and the shared config inside it) from the id
+ * alone.
+ */
+export const projectPathFromId = (projectId) => {
+  if (typeof projectId !== 'string' || !projectId.startsWith('path_')) return '';
+  const encoded = projectId.slice('path_'.length);
+  if (!encoded || !/^[A-Za-z0-9_-]+$/.test(encoded)) return '';
+  try {
+    return Buffer.from(encoded, 'base64url').toString('utf8');
+  } catch {
+    return '';
+  }
+};