projectkeeper 0.0.0-stage → 1.0.0

package/src/store/versions.ts

@@ -0,0 +1,172 @@
+/**
+ * Saved versions of the picture, for `Compare` (Spec §6.3, §6.5; owner D45). Two points in time can only be
+ * compared if both were kept, so the picture is saved at the moments the owner would want to compare from: each
+ * time they open the project, and at the end of each round of organizing.
+ *
+ * A version holds what a comparison needs — the objects, their state, where they hang, the relations and their
+ * assessments — not the whole asset set. On this project that is about 59 KB, 11 KB gzipped, so a year of daily
+ * versions is a few megabytes.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { gunzipSync, gzipSync } from 'node:zlib';
+import { join } from 'node:path';
+import type { ProjectStore } from './project-store.ts';
+
+export type VersionReason = 'Opened' | 'Organized' | 'Asked';
+
+export interface VersionNode {
+  readonly id: string;
+  readonly category: string;
+  readonly label: string;
+  readonly validity: string;
+  readonly progress: string | null;
+  readonly acceptance: string;
+  readonly areaId: string | null;
+  readonly parentId: string | null;
+  /** A digest of the object's own text, so a rewrite shows up as a content change without keeping the text twice. */
+  readonly text: string;
+}
+export interface VersionRelation {
+  readonly id: string;
+  readonly type: string;
+  readonly from: string;
+  readonly to: string;
+  readonly assessment: string;
+}
+export interface Version {
+  readonly id: string;
+  readonly at: string;
+  readonly reason: VersionReason;
+  readonly nodes: readonly VersionNode[];
+  readonly relations: readonly VersionRelation[];
+}
+export interface VersionInfo { readonly id: string; readonly at: string; readonly reason: VersionReason; readonly nodes: number; readonly relations: number; readonly bytes: number }
+
+const digest = (s: string): string => createHash('sha1').update(s).digest('hex').slice(0, 12);
+const versionsDir = (projectDir: string) => join(projectDir, 'versions');
+
+/** The current picture, in the shape a comparison reads. */
+export function snapshot(store: ProjectStore, reason: VersionReason, at = new Date().toISOString()): Version {
+  const textOf = (n: { refKind: string; refId: string }): string => {
+    if (n.refKind === 'reference') return store.reference.get(n.refId)?.text ?? '';
+    if (n.refKind === 'thread') { const t = store.threads.get(n.refId); return t ? `${t.doing}\0${t.results}\0${t.unresolved}\0${t.doneMeans ?? ''}` : ''; }
+    if (n.refKind === 'change') return store.changes.get(n.refId)?.summary ?? '';
+    return '';
+  };
+  return {
+    id: at.replace(/[:.]/g, '-'),
+    at,
+    reason,
+    nodes: store.nodes.all().map((n) => ({
+      id: n.id, category: n.category, label: n.label, validity: n.validity, progress: n.progress ?? null,
+      acceptance: (n as { acceptance?: string }).acceptance ?? '', areaId: n.areaId ?? null, parentId: n.parentWorkId ?? null,
+      text: digest(textOf(n)),
+    })),
+    relations: store.relations.all().map((r) => ({ id: r.id, type: r.type, from: r.from, to: r.to, assessment: r.assessment })),
+  };
+}
+
+/** Save a version unless the picture is identical to the newest one; returns what was saved, or null. */
+export function saveVersion(projectDir: string, store: ProjectStore, reason: VersionReason, keep = 400): Version | null {
+  const dir = versionsDir(projectDir);
+  mkdirSync(dir, { recursive: true });
+  const version = snapshot(store, reason);
+  const list = listVersions(projectDir);
+  const newest = list[list.length - 1];
+  if (newest) {
+    const previous = readVersion(projectDir, newest.id);
+    if (previous && sameShape(previous, version)) return null;
+  }
+  writeFileSync(join(dir, `${version.id}__${reason}.json.gz`), gzipSync(Buffer.from(JSON.stringify(version), 'utf8')));
+  const all = listVersions(projectDir);
+  for (const old of all.slice(0, Math.max(0, all.length - keep))) rmSync(join(dir, fileOf(old.id, old.reason)), { force: true });
+  return version;
+}
+
+const fileOf = (id: string, reason: string) => `${id}__${reason}.json.gz`;
+
+function sameShape(a: Version, b: Version): boolean {
+  if (a.nodes.length !== b.nodes.length || a.relations.length !== b.relations.length) return false;
+  const key = (v: Version) => JSON.stringify([v.nodes.map((n) => [n.id, n.validity, n.progress, n.acceptance, n.areaId, n.parentId, n.text, n.label]).sort(), v.relations.map((r) => [r.id, r.assessment, r.from, r.to]).sort()]);
+  return key(a) === key(b);
+}
+
+export function listVersions(projectDir: string): VersionInfo[] {
+  const dir = versionsDir(projectDir);
+  if (!existsSync(dir)) return [];
+  const out: VersionInfo[] = [];
+  for (const file of readdirSync(dir)) {
+    const m = /^(.+)__(Opened|Organized|Asked)\.json\.gz$/.exec(file);
+    if (!m) continue;
+    const raw = readFileSync(join(dir, file));
+    let v: Version | null = null;
+    try { v = JSON.parse(gunzipSync(raw).toString('utf8')) as Version; } catch { continue; }
+    out.push({ id: m[1]!, at: v.at, reason: m[2] as VersionReason, nodes: v.nodes.length, relations: v.relations.length, bytes: raw.length });
+  }
+  return out.sort((a, b) => a.at.localeCompare(b.at));
+}
+
+export function readVersion(projectDir: string, id: string): Version | null {
+  const dir = versionsDir(projectDir);
+  if (!existsSync(dir)) return null;
+  const file = readdirSync(dir).find((f) => f.startsWith(`${id}__`));
+  if (!file) return null;
+  try { return JSON.parse(gunzipSync(readFileSync(join(dir, file))).toString('utf8')) as Version; } catch { return null; }
+}
+
+export type DiffKind = 'Added' | 'Removed' | 'Content changed' | 'Regrouped' | 'Relinked';
+export interface DiffItem {
+  readonly kind: DiffKind;
+  readonly id: string;
+  readonly label: string;
+  readonly category: string;
+  /** What changed, in the words of the fields that differ; empty for Added and Removed. */
+  readonly detail: string;
+}
+
+/**
+ * The five kinds of difference between two versions (Spec §6.3):
+ * `Added` and `Removed` are objects; `Content changed` is an object whose own text, state, progress or acceptance
+ * moved; `Regrouped` is an object that hangs somewhere else now; `Relinked` is an object whose relations changed.
+ * An object can only be counted once, in the first kind that applies, so the counts add up to the objects touched.
+ */
+export function diffVersions(before: Version, after: Version): { items: DiffItem[]; counts: Record<DiffKind, number> } {
+  const a = new Map(before.nodes.map((n) => [n.id, n]));
+  const b = new Map(after.nodes.map((n) => [n.id, n]));
+  const relKey = (r: VersionRelation) => `${r.type}:${r.from}>${r.to}`;
+  const relsOf = (v: Version) => {
+    const m = new Map<string, Set<string>>();
+    for (const r of v.relations) for (const end of [r.from, r.to]) { if (!m.has(end)) m.set(end, new Set()); m.get(end)!.add(`${relKey(r)}#${r.assessment}`); }
+    return m;
+  };
+  const ra = relsOf(before), rb = relsOf(after);
+  const items: DiffItem[] = [];
+  for (const [id, n] of b) if (!a.has(id)) items.push({ kind: 'Added', id, label: n.label, category: n.category, detail: '' });
+  for (const [id, n] of a) if (!b.has(id)) items.push({ kind: 'Removed', id, label: n.label, category: n.category, detail: '' });
+  for (const [id, after1] of b) {
+    const before1 = a.get(id);
+    if (!before1) continue;
+    const changed: string[] = [];
+    if (before1.validity !== after1.validity) changed.push(`validity ${before1.validity} → ${after1.validity}`);
+    if (before1.progress !== after1.progress) changed.push(`progress ${before1.progress ?? '—'} → ${after1.progress ?? '—'}`);
+    if (before1.acceptance !== after1.acceptance) changed.push(`acceptance ${before1.acceptance || '—'} → ${after1.acceptance || '—'}`);
+    if (before1.label !== after1.label) changed.push('name rewritten');
+    if (before1.text !== after1.text) changed.push('text rewritten');
+    if (changed.length > 0) { items.push({ kind: 'Content changed', id, label: after1.label, category: after1.category, detail: changed.join('; ') }); continue; }
+    if (before1.areaId !== after1.areaId || before1.parentId !== after1.parentId) {
+      const name = (x: string | null) => (x ? b.get(x)?.label ?? a.get(x)?.label ?? x : 'nothing');
+      items.push({ kind: 'Regrouped', id, label: after1.label, category: after1.category, detail: `hangs from ${name(before1.areaId ?? before1.parentId)} → ${name(after1.areaId ?? after1.parentId)}` });
+      continue;
+    }
+    const setA = ra.get(id) ?? new Set<string>(), setB = rb.get(id) ?? new Set<string>();
+    const gained = [...setB].filter((x) => !setA.has(x)).length;
+    const lost = [...setA].filter((x) => !setB.has(x)).length;
+    if (gained || lost) items.push({ kind: 'Relinked', id, label: after1.label, category: after1.category, detail: `${gained} relation${gained === 1 ? '' : 's'} gained, ${lost} lost` });
+  }
+  const counts = { 'Added': 0, 'Removed': 0, 'Content changed': 0, 'Regrouped': 0, 'Relinked': 0 } as Record<DiffKind, number>;
+  for (const i of items) counts[i.kind]++;
+  const order: DiffKind[] = ['Added', 'Content changed', 'Regrouped', 'Relinked', 'Removed'];
+  items.sort((x, y) => order.indexOf(x.kind) - order.indexOf(y.kind) || x.label.localeCompare(y.label));
+  return { items, counts };
+}

package/src/store/workspace.ts

@@ -0,0 +1,216 @@
+/**
+ * The workspace: which projects the owner added, plus settings that are not project assets
+ * (port, chosen model). Lives at `~/.projectkeeper/workspace.json`.
+ */
+import type { RoundStepKind } from '../model/k-types.ts';
+import { createHash } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import type { Project, ScopeItem, ScopeQuestion } from '../model/types.ts';
+import { slug } from '../model/ids.ts';
+import { canonicalPath, expandHome } from '../util/paths.ts';
+import { writeJsonAtomic } from './json-file.ts';
+import { ensureHome, projectKeeperHome, workspaceFile } from './paths.ts';
+
+export interface ModelChoice {
+  readonly provider: string;
+  readonly id: string;
+  readonly thinking: string | null;
+}
+/** Another key. It runs under a provider id of its own, so it has its own lanes and its own quota window; the key itself
+ *  stays in the named environment variable and is read there when a request is sent. A key for a provider pi already
+ *  knows names it in `like`; a key for a provider pi does not know (owner 2026-09-22: Xiaomi MiMo) brings its own
+ *  endpoint, API and models instead. */
+export interface ExtraKey {
+  readonly provider: string;    // the id this key runs under, e.g. `zai-coding-cn-team`
+  readonly like?: string;       // the provider whose endpoint and models it uses, e.g. `zai-coding-cn`
+  readonly apiKeyEnv: string;   // the environment variable that holds the key
+  readonly name?: string;
+  readonly baseUrl?: string;    // with `api` and `models`: a provider of its own, e.g. `https://api.xiaomimimo.com/v1`
+  readonly api?: string;        // pi's API family for it, e.g. `openai-completions`
+  readonly models?: readonly ExtraKeyModel[];
+}
+/** One model of a provider an extra key brings itself; the fields are the ones pi's providers declare. */
+export interface ExtraKeyModel {
+  readonly id: string;
+  readonly name?: string;
+  readonly reasoning?: boolean;
+  readonly contextWindow: number;
+  readonly maxTokens: number;
+  readonly input?: readonly ('text' | 'image')[];
+  readonly cost?: { readonly input?: number; readonly output?: number; readonly cacheRead?: number; readonly cacheWrite?: number };
+  readonly thinkingLevelMap?: Readonly<Record<string, string | null>>;
+  readonly compat?: Readonly<Record<string, unknown>>;   // e.g. { thinkingFormat: 'deepseek', maxTokensField: 'max_tokens' }
+}
+export interface WorkspaceSettings {
+  readonly port: number;
+  readonly model: ModelChoice | null;
+  readonly modelBackups: readonly ModelChoice[];   // used in order when the active provider reports its quota exhausted; the switch is visible, never silent
+  readonly keeperAgent: 'pi';
+  readonly organizingLanesPerKey?: number;         // automatic organizing jobs per key at once (the chosen model and each backup are keys); trial setting 2026-09-17
+  readonly extraKeys?: readonly ExtraKey[];         // more keys for known providers (owner 2026-09-18: a third Zhipu Coding Plan key); name them in model or modelBackups to use them
+  /** Automatic jobs at once on one key, set for that key (§6.10 每把 key 同时跑几路, D105); a key not listed runs `organizingLanesPerKey`. */
+  readonly keyLanes?: Readonly<Record<string, number>>;
+  readonly watchProjects?: boolean;                 // false for a controlled trial: the home works through what it holds and takes in no new changes, so runs started from one snapshot see the same input (owner 2026-09-18)
+  // From the follow-up experiment's arm B (owner 2026-09-18); its other settings went once every round was one main job (D59).
+  readonly routes?: Readonly<Record<string, string>>;   // job route or kind → model id on the same key's provider, e.g. { "frame": "glm-5.3", "relook": "glm-5.3" }
+  /**
+   * The model and thinking level of each step of a clerk-method round (Spec §3.3, CKC-03 AC-29, CKC-23 AC-11), on the
+   * provider of the key a lane runs on. A step left out runs on the key's own model and thinking level. The baseline of
+   * increment K runs every step on glm-5.3 at the highest thinking (D87, D90).
+   */
+  readonly steps?: Readonly<Partial<Record<RoundStepKind, { readonly model?: string; readonly thinking?: string }>>>;
+}
+interface WorkspaceFile {
+  readonly version: 1;
+  readonly projects: Project[];
+  readonly settings: WorkspaceSettings;
+  readonly lastProjectId: string | null;
+}
+
+const DEFAULT_SETTINGS: WorkspaceSettings = { port: 4870, model: null, modelBackups: [], keeperAgent: 'pi' };
+
+/** The settings file is there and cannot be read as a workspace. The message names the file and says what to do. */
+export class WorkspaceFileError extends Error {
+  readonly file: string;
+  constructor(file: string, what: string) {
+    super(`Cannot read the settings file ${file}: ${what}. Correct it and start again, or move the file away to start with an empty workspace (the projects' assets under projects/ stay where they are). Nothing was changed.`);
+    this.name = 'WorkspaceFileError';
+    this.file = file;
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Read the settings file. Every key it lacks takes its default — `projects` an empty list, `settings` the defaults,
+ * a project's lists empty — so a file written by hand or by an earlier version loads. What cannot be given a default
+ * (text that is not JSON, a project without an id or without locations) is said, with the file's name, and the file is
+ * left as it is: starting with an empty workspace instead would write that over the owner's projects on the next save.
+ */
+function readWorkspaceFile(file: string): WorkspaceFile {
+  if (!existsSync(file)) return { version: 1, projects: [], settings: DEFAULT_SETTINGS, lastProjectId: null };
+  let raw: unknown;
+  try { raw = JSON.parse(readFileSync(file, 'utf8').replace(/^/, '')); }
+  catch (error) { throw new WorkspaceFileError(file, `it is not valid JSON (${(error as Error).message})`); }
+  if (!isRecord(raw)) throw new WorkspaceFileError(file, 'it does not hold a JSON object ({ "projects": […], "settings": {…} })');
+  if (raw.projects !== undefined && !Array.isArray(raw.projects)) throw new WorkspaceFileError(file, '"projects" is not a list');
+  if (raw.settings !== undefined && raw.settings !== null && !isRecord(raw.settings)) throw new WorkspaceFileError(file, '"settings" is not an object');
+  const projects = ((raw.projects as unknown[] | undefined) ?? []).map((entry, index): Project => {
+    const where = `project ${index + 1} of "projects"`;
+    if (!isRecord(entry)) throw new WorkspaceFileError(file, `${where} is not an object`);
+    if (typeof entry.id !== 'string' || !entry.id.trim()) throw new WorkspaceFileError(file, `${where} has no "id"`);
+    if (!Array.isArray(entry.locations) || entry.locations.length === 0 || entry.locations.some((l) => typeof l !== 'string' || !l.trim())) {
+      throw new WorkspaceFileError(file, `${where} (${entry.id}) has no "locations": a list with at least one directory`);
+    }
+    const list = (key: string): unknown[] => (Array.isArray(entry[key]) ? entry[key] as unknown[] : []);
+    return {
+      ...(entry as unknown as Project),
+      name: typeof entry.name === 'string' && entry.name.trim() ? entry.name : entry.id,
+      // One spelling of each location, the file system's own: the one a project is added in (see `add`).
+      locations: (entry.locations as string[]).map((l) => canonicalPath(l)),
+      scope: list('scope') as ScopeItem[], scopeQuestions: list('scopeQuestions') as ScopeQuestion[],
+      keeperFiles: list('keeperFiles') as Project['keeperFiles'], roles: list('roles') as string[],
+      language: typeof entry.language === 'string' && entry.language ? entry.language : 'en',
+      organizingPaused: entry.organizingPaused === true,
+      createdAt: typeof entry.createdAt === 'string' && entry.createdAt ? entry.createdAt : statSync(file).mtime.toISOString(),
+      lastOpenedAt: typeof entry.lastOpenedAt === 'string' ? entry.lastOpenedAt : null,
+      lastScopedAt: typeof entry.lastScopedAt === 'string' ? entry.lastScopedAt : null,
+    };
+  });
+  const settings = { ...DEFAULT_SETTINGS, ...((raw.settings as Partial<WorkspaceSettings> | null | undefined) ?? {}) };
+  const lastProjectId = typeof raw.lastProjectId === 'string' && projects.some((p) => p.id === raw.lastProjectId) ? raw.lastProjectId : null;
+  return { version: 1, projects, settings, lastProjectId };
+}
+
+export class Workspace extends EventEmitter {
+  readonly home: string;
+  private data: WorkspaceFile;
+
+  private constructor(home: string, data: WorkspaceFile) {
+    super();
+    this.home = home;
+    this.data = data;
+  }
+
+  /**
+   * Open the workspace of a home. A settings file that is not there yet is an empty workspace. One that is there is
+   * read as it is and never replaced because of what it holds: a key it lacks (a file written by hand, or by an earlier
+   * version) takes its default, and a file that cannot be read as a workspace stops here with a message naming it.
+   */
+  static open(home = projectKeeperHome()): Workspace {
+    const at = canonicalPath(home);
+    return new Workspace(at, readWorkspaceFile(workspaceFile(at)));
+  }
+
+  get settings(): WorkspaceSettings { return this.data.settings; }
+  get lastProjectId(): string | null { return this.data.lastProjectId; }
+
+  list(): readonly Project[] { return this.data.projects; }
+
+  get(id: string): Project | undefined { return this.data.projects.find((p) => p.id === id); }
+
+  /** Project id: name slug plus a hash of the first location, stable across renames of the store. */
+  static idFor(name: string, firstLocation: string): string {
+    const hash = createHash('sha1').update(canonicalPath(firstLocation).toLowerCase()).digest('hex').slice(0, 6);
+    return `${slug(name)}-${hash}`;
+  }
+
+  /**
+   * Add a project. Its locations are kept in the file system's own spelling (`canonicalPath`), whichever way they were
+   * given — a short (8.3) name, a junction, a `subst` drive, another case: that is the spelling git reports the
+   * repository and its worktrees in, and every later comparison is made on it. A location typed with `~` is under
+   * the home directory.
+   */
+  add(name: string, locations: readonly string[]): Project {
+    const cleaned = [...new Set(locations.map((l) => canonicalPath(expandHome(l))))];
+    if (cleaned.length === 0) throw new Error('A project needs at least one location');
+    const id = Workspace.idFor(name, cleaned[0]!);
+    if (this.get(id)) throw new Error(`Project already exists: ${id}`);
+    const now = new Date().toISOString();
+    const project: Project = {
+      id, name: name.trim(), locations: cleaned, scope: [], scopeQuestions: [], keeperFiles: [], roles: [],
+      language: 'en', organizingPaused: false, createdAt: now, lastOpenedAt: null, lastScopedAt: null,
+    };
+    this.data = { ...this.data, projects: [...this.data.projects, project], lastProjectId: id };
+    this.save();
+    this.emit('change', { kind: 'projects' });
+    return project;
+  }
+
+  update(project: Project): Project {
+    const index = this.data.projects.findIndex((p) => p.id === project.id);
+    if (index < 0) throw new Error(`Unknown project: ${project.id}`);
+    const projects = [...this.data.projects];
+    projects[index] = project;
+    this.data = { ...this.data, projects };
+    this.save();
+    this.emit('change', { kind: 'project', id: project.id });
+    return project;
+  }
+
+  remove(id: string): void {
+    this.data = { ...this.data, projects: this.data.projects.filter((p) => p.id !== id),
+      lastProjectId: this.data.lastProjectId === id ? null : this.data.lastProjectId };
+    this.save();
+    this.emit('change', { kind: 'projects' });
+  }
+
+  setLastProject(id: string | null): void {
+    if (this.data.lastProjectId === id) return;
+    this.data = { ...this.data, lastProjectId: id };
+    this.save();
+  }
+
+  setSettings(patch: Partial<WorkspaceSettings>): WorkspaceSettings {
+    this.data = { ...this.data, settings: { ...this.data.settings, ...patch } };
+    this.save();
+    this.emit('change', { kind: 'settings' });
+    return this.data.settings;
+  }
+
+  private save(): void {
+    ensureHome(this.home);
+    writeJsonAtomic(workspaceFile(this.home), this.data);
+  }
+}