projectkeeper 0.0.0-stage → 1.0.0

package/src/server/keys-api.ts

@@ -0,0 +1,239 @@
+/**
+ * `Keeper` → `Model provider` and `Usage` per round (Spec §6.10 "key、模型与路由", §3.10; D38, D105; CKC-03 AC-29,
+ * AC-33～AC-37): the owner's own keys — add, replace, remove, check — beside the keys configured outside the product;
+ * the project's route — main model, each step's model or whom it follows, the backup order — and each key's jobs at once;
+ * and, in `Usage`, one row per round split by model.
+ *
+ * A key's value comes in on `POST /api/keys` and `POST /api/keys/:id`, goes to the runtime, and never comes back out:
+ * every answer here carries the full mask at most. A refused request answers 400 with the reason, so nothing a key was
+ * part of reaches the server log (http.ts logs only a 500's stack).
+ */
+import type { App } from './app.ts';
+import { HttpApp, HttpError } from './http.ts';
+import type { KeeperJob, Usage } from '../model/types.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import { cleanKeyValue } from '../keeper/own-keys.ts';
+import { ROUTE_STEPS, wantOf } from '../keeper/route.ts';
+import { THINKING_LEVELS } from '../keeper/clerk-steps.ts';
+import { roundJobs } from './keeper-page.ts';
+
+const fail = (e: unknown): never => { throw e instanceof HttpError ? e : new HttpError(400, e instanceof Error ? e.message : String(e)); };
+const str = (v: unknown): string | null => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+/** The page's view of the keys and the project's route. */
+export async function modelProviderView(app: App, projectId: string) {
+  const keeper = app.keeper;
+  const keys = await keeper.keysView();
+  const name = (id: string) => keys.find((k) => k.id === id)?.name ?? id;
+  const usable = (id: string) => { const k = keys.find((x) => x.id === id); return Boolean(k && (k.state.status === 'Usable' || k.state.status === 'Rate-limited')); };
+  const route = keeper.routeFor(projectId);
+  const state = await keeper.providerState(projectId);
+  const lanes = keeper.laneState(projectId);
+  // The key the main row shows is the one the project runs on now: its own route's, else the machine's (a provider named
+  // where a key is meant is that provider's first usable key), else — no main model set anywhere — the key in use.
+  const keyFor = (provider: string): string => (keys.some((k) => k.id === provider) ? provider : keys.find((k) => k.provider === provider && usable(k.id))?.id ?? keys.find((k) => k.provider === provider)?.id ?? provider);
+  const mainModel = route.main ? { ...route.main, provider: keyFor(route.main.provider) } : state.model ? { provider: state.model.provider, id: state.model.id, thinking: state.model.thinking } : null;
+  const main = mainModel ? { ...mainModel, keyName: name(mainModel.provider), usable: usable(mainModel.provider), chosen: Boolean(route.main) } : null;
+  // The models a step can be set to: those of the providers with a usable key (§6.10 可选的模型来自有可用 key 的 provider), one entry per provider and model.
+  const offered = new Map<string, { provider: string; providerName: string; model: string; keys: string[]; priced: boolean }>();
+  for (const k of keys) {
+    if (!usable(k.id)) continue;
+    for (const m of k.models) {
+      const at = `${k.provider}/${m.id}`;
+      const o = offered.get(at) ?? { provider: k.provider, providerName: k.providerName, model: m.id, keys: [], priced: m.priced };
+      o.keys.push(k.name);
+      offered.set(at, o);
+    }
+  }
+  // The provider a key runs for (an extra key's `like`, an own key's provider); a provider id stays itself.
+  const familyOf = (id: string): string => keys.find((k) => k.id === id)?.provider ?? id;
+  const mainFamily = main ? familyOf(main.provider) : null;
+  /** Where a step's own model sits among the offered ones: the provider it names, else the main key's provider when that
+   *  carries it (a step set by model alone runs on the main key first), else the first provider that offers it. */
+  const placeOf = (own: { readonly provider?: string; readonly model?: string } | null): string | null => {
+    if (!own?.model) return null;
+    const family = own.provider ? familyOf(own.provider)
+      : mainFamily && offered.has(`${mainFamily}/${own.model}`) ? mainFamily
+        : [...offered.values()].find((o) => o.model === own.model)?.provider ?? mainFamily ?? '';
+    return `${family}|${own.model}`;
+  };
+  return {
+    keys,
+    providers: keeper.keyProviders(),
+    thinking: ['off', ...THINKING_LEVELS],
+    route: {
+      own: route.own,
+      main,
+      // The main key is first in the order already; a backup naming it again (a machine with no main model set, whose first backup runs) is not listed twice.
+      backups: route.backups.filter((b) => b.provider !== main?.provider).map((b) => ({ ...b, keyName: name(b.provider), usable: usable(b.provider) })),
+      steps: ROUTE_STEPS.map((kind) => {
+        const own = route.steps[kind] ?? null;
+        const routeNow = { ...route, main: route.main ?? mainModel };
+        const want = wantOf(routeNow, kind);
+        // Whom the step follows when it has no model of its own, and the model that gives it — said even while it has one,
+        // since the select offers going back to it.
+        const steps = { ...routeNow.steps };
+        if (own?.thinking) steps[kind] = { thinking: own.thinking }; else delete steps[kind];
+        const without = wantOf({ ...routeNow, steps }, kind);
+        return { kind, own, model: want.model, provider: want.provider, thinking: want.thinking, follows: want.follows, followsWhom: without.follows, followsModel: without.model, place: placeOf(own) };
+      }),
+    },
+    offered: [...offered.values()],
+    inUse: state.model ? { ...state.model, keyName: name(state.model.provider) } : null,
+    fallback: state.fallback ? { ...state.fallback, keyName: name(state.fallback.provider), fromName: name(state.fallback.from.provider) } : null,
+    connected: state.connected,
+    reason: state.reason,
+    lanes: { lanesPerKey: lanes.lanesPerKey, total: lanes.total, keys: lanes.keys.map((k) => ({ ...k, keyName: name(k.provider) })) },
+    switches: state.switches,
+  };
+}
+
+// ───────────────────────── Usage per round per model (§3.10, §6.10 `Usage`; CKC-03 AC-37) ─────────────────────────
+
+export interface ModelUsage {
+  /** The model, as the owner reads it: provider and model id. */
+  readonly model: string;
+  readonly keys: readonly string[];
+  readonly steps: readonly { readonly kind: string; readonly count: number }[];
+  /** The time its jobs ran, added up (jobs that ran side by side each count). */
+  readonly timeMs: number;
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  /** Null when the provider reports no price for it: the tokens are what there is. */
+  readonly cost: number | null;
+  readonly priced: boolean;
+}
+export interface RoundUsage {
+  readonly id: string;
+  readonly number: number;
+  readonly kind: string;
+  readonly status: string;
+  readonly startedAt: string;
+  readonly endedAt: string | null;
+  readonly wallMs: number;
+  readonly cost: number | null;
+  readonly input: number;
+  readonly output: number;
+  readonly byModel: readonly ModelUsage[];
+}
+
+/** Steps in the order a round runs them; a subagent a step sent comes last. */
+const STEP_ORDER = ['session-drafts', 'orientation', 'skeleton', 'main', 'lane', 'dig', 'cross-check', 'synthesis', 'spot-check'];
+const stepOrder = (kind: string): number => { const i = STEP_ORDER.indexOf(kind); return i < 0 ? STEP_ORDER.length : i; };
+const jobTime = (j: KeeperJob, now: number): number => j.timing?.wallMs ?? (j.startedAt ? (j.endedAt ? Date.parse(j.endedAt) : now) - Date.parse(j.startedAt) : 0);
+
+/**
+ * One row per round, newest first: its wall time and cost, split by the model each job ran on — the steps each model
+ * carried, their time, input and output tokens and cost. A model the provider gives no price for says so (`priced`
+ * false, cost null) and gives its tokens. Read from the jobs as recorded: the model a job ran on is on the job.
+ */
+export function usageByRound(
+  store: ProjectStore,
+  look: { readonly keyName: (id: string) => string; readonly familyOf: (id: string) => string; readonly priced: (provider: string, model: string) => boolean | null },
+  now = Date.now(),
+): RoundUsage[] {
+  const rounds = store.clerkRounds.all().sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+  return rounds.map((round) => {
+    const jobs = roundJobs(store, round).filter((j) => j.agent !== 'program' && j.model);
+    const groups = new Map<string, { keys: Set<string>; steps: Map<string, number>; timeMs: number; usage: Usage; priced: boolean }>();
+    for (const j of jobs) {
+      const family = look.familyOf(j.model!.provider);
+      const at = `${family}/${j.model!.id}`;
+      const g = groups.get(at) ?? { keys: new Set<string>(), steps: new Map<string, number>(), timeMs: 0, usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: null }, priced: false };
+      g.keys.add(look.keyName(j.model!.provider));
+      const kind = j.step?.kind ?? 'subagent';
+      g.steps.set(kind, (g.steps.get(kind) ?? 0) + 1);
+      g.timeMs += Math.max(0, jobTime(j, now));
+      const listed = look.priced(j.model!.provider, j.model!.id);
+      const priced = listed ?? (j.usage.cost !== null && j.usage.cost > 0);
+      g.priced = g.priced || priced;
+      g.usage = { input: g.usage.input + j.usage.input, output: g.usage.output + j.usage.output, cacheRead: g.usage.cacheRead + j.usage.cacheRead, cacheWrite: g.usage.cacheWrite + j.usage.cacheWrite, cost: priced && j.usage.cost !== null ? (g.usage.cost ?? 0) + j.usage.cost : g.usage.cost };
+      groups.set(at, g);
+    }
+    const byModel: ModelUsage[] = [...groups.entries()].map(([model, g]) => ({
+      model, keys: [...g.keys].sort(), steps: [...g.steps.entries()].map(([kind, count]) => ({ kind, count })).sort((a, b) => stepOrder(a.kind) - stepOrder(b.kind)), timeMs: g.timeMs,
+      input: g.usage.input, output: g.usage.output, cacheRead: g.usage.cacheRead, cost: g.priced ? g.usage.cost ?? 0 : null, priced: g.priced,
+    })).sort((a, b) => b.timeMs - a.timeMs);
+    const costs = byModel.filter((m) => m.cost !== null);
+    return {
+      id: round.id, number: round.number, kind: round.kind, status: round.status, startedAt: round.startedAt, endedAt: round.endedAt,
+      wallMs: (round.endedAt ? Date.parse(round.endedAt) : now) - Date.parse(round.startedAt),
+      cost: costs.length ? costs.reduce((n, m) => n + (m.cost ?? 0), 0) : null,
+      input: byModel.reduce((n, m) => n + m.input, 0), output: byModel.reduce((n, m) => n + m.output, 0),
+      byModel,
+    };
+  });
+}
+
+export function registerKeyRoutes(http: HttpApp, app: App): void {
+  http.route('GET', '/api/projects/:id/model-provider', ({ params }) => modelProviderView(app, params.id!));
+
+  // A key in: provider, an optional name, the key. Saved on this machine, checked at once; only the mask comes back.
+  http.route('POST', '/api/keys', async ({ body }) => {
+    const b = (body ?? {}) as Record<string, unknown>;
+    try {
+      const provider = str(b.provider);
+      if (!provider) throw new Error('Choose the provider the key is for');
+      const value = cleanKeyValue(b.key);
+      const r = await app.keeper.addKey(provider, str(b.name), value);
+      return { key: r.key, check: r.check };
+    } catch (e) { return fail(e); }
+  });
+  http.route('POST', '/api/keys/:key', async ({ params, body }) => {
+    const b = (body ?? {}) as Record<string, unknown>;
+    try {
+      if (!app.keeper.ownKeys.get(params.key!)) throw new HttpError(404, 'Only a key saved here can be replaced; a key configured outside ProjectKeeper is changed where it is set');
+      const value = b.key === undefined || b.key === '' ? null : cleanKeyValue(b.key);
+      return await app.keeper.replaceKey(params.key!, value, str(b.name));
+    } catch (e) { return fail(e); }
+  });
+  http.route('DELETE', '/api/keys/:key', async ({ params }) => {
+    if (!app.keeper.ownKeys.get(params.key!)) throw new HttpError(404, 'Only a key saved here can be removed; a key configured outside ProjectKeeper is removed where it is set');
+    return app.keeper.removeKey(params.key!);
+  });
+  http.route('POST', '/api/keys/:key/check', async ({ params }) => {
+    if (!app.keeper.models.getProvider(params.key!)) throw new HttpError(404, `No key ${params.key}`);
+    return { check: await app.keeper.checkKeyNow(params.key!) };
+  });
+  // A key's own number of jobs at once; `null` gives it back to the setting for every key.
+  http.route('POST', '/api/keys/:key/lanes', ({ params, body }) => {
+    const raw = (body as { lanes?: unknown } | null)?.lanes;
+    if (raw === null) return { lanes: app.keeper.setKeyLanes(params.key!, null) };
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1 || n > 32) throw new HttpError(400, 'lanes must be a number from 1 to 32');
+    return { lanes: app.keeper.setKeyLanes(params.key!, n) };
+  });
+
+  // The project's route: { model?: {provider, id, thinking}, backups?: [{provider, id, thinking}], steps?: { kind: {provider?, model?, thinking?} | null } }.
+  http.route('POST', '/api/projects/:id/route', ({ params, body }) => {
+    const b = (body ?? {}) as Record<string, unknown>;
+    const model = (m: unknown) => { const o = (m ?? {}) as Record<string, unknown>; const provider = str(o.provider); const id = str(o.id); if (!provider || !id) throw new HttpError(400, 'A model is a key (provider) and a model id'); return { provider, id, thinking: str(o.thinking) }; };
+    try {
+      app.project(params.id!);
+      const steps = b.steps === undefined ? undefined : (() => {
+        if (!b.steps || typeof b.steps !== 'object' || Array.isArray(b.steps)) throw new HttpError(400, 'steps must be an object keyed by step');
+        return Object.fromEntries(Object.entries(b.steps as Record<string, unknown>).map(([k, v]) => {
+          if (v === null) return [k, null];
+          const o = (v ?? {}) as Record<string, unknown>;
+          return [k, { ...(str(o.provider) ? { provider: str(o.provider)! } : {}), ...(str(o.model) ? { model: str(o.model)! } : {}), ...(str(o.thinking) ? { thinking: str(o.thinking)! } : {}) }];
+        }));
+      })();
+      app.keeper.setRoute(params.id!, {
+        ...(b.model !== undefined ? { model: model(b.model) } : {}),
+        ...(Array.isArray(b.backups) ? { backups: b.backups.map(model) } : {}),
+        ...(steps ? { steps } : {}),
+      });
+      return modelProviderView(app, params.id!);
+    } catch (e) { return fail(e); }
+  });
+
+  http.route('GET', '/api/projects/:id/usage-rounds', async ({ params }) => {
+    const keys = await app.keeper.keysView().catch(() => []);
+    const keyName = (id: string) => keys.find((k) => k.id === id)?.name ?? id;
+    const priced = (provider: string, model: string): boolean | null => {
+      try { const m = app.keeper.models.getModel(provider, model) ?? app.keeper.models.getModel(app.keeper.familyOf(provider), model); return m ? m.cost.input > 0 || m.cost.output > 0 : null; } catch { return null; }
+    };
+    return { rounds: usageByRound(app.store(params.id!), { keyName, familyOf: (id) => app.keeper.familyOf(id), priced }) };
+  });
+}

package/src/server/project-folder-api.ts

@@ -0,0 +1,104 @@
+/**
+ * Owner-facing grant for the Project folder standing authorization (CKC-26 AC-7–AC-10), and its state as the Keeper page
+ * shows it. The owner gives it on that page (`Authorize…`) and withdraws it there (`Withdraw`, the revoke route of
+ * every standing authorization).
+ */
+import { existsSync } from 'node:fs';
+import { isAbsolute, relative, sep } from 'node:path';
+import { canonicalPath } from '../util/paths.ts';
+import type { App } from './app.ts';
+import { HttpApp, HttpError, requireString } from './http.ts';
+import { grantProjectFolderAuthorization, projectFolderPath, syncProjectFolder, type ProjectFolderAuthorizationInput } from '../keeper/project-folder.ts';
+
+export function registerProjectFolderRoutes(http: HttpApp, app: App): void {
+  http.route('POST', '/api/projects/:id/authorizations/project-folder', ({ params, body }) => {
+    const project = app.project(params.id!);
+    const input = (body ?? {}) as Record<string, unknown>;
+    const quote = requireString(input.quote, 'quote');
+    if (input.path !== undefined && (typeof input.path !== 'string' || !input.path.trim())) throw new HttpError(400, 'path must be a nonempty string');
+    if (input.commits !== undefined && typeof input.commits !== 'boolean') throw new HttpError(400, 'commits must be a boolean');
+    if (input.sourceId !== undefined && (typeof input.sourceId !== 'string' || !input.sourceId.trim())) throw new HttpError(400, 'sourceId must be a nonempty string');
+    const path = input.path as string | undefined;
+    const sourceId = input.sourceId as string | undefined;
+    try {
+      return grantProjectFolder(app, project.id, { path, commits: input.commits as boolean | undefined, quote, sourceId });
+    } catch (error) {
+      if (error instanceof HttpError) throw error;
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.startsWith('An active Project folder')) throw new HttpError(409, message);
+      if (/Invalid project folder|must be inside|must not be hidden|Unsafe project folder|escapes through|chosen folder already contains|folder contains files outside|Invalid owner source/.test(message)) throw new HttpError(400, message);
+      throw error;
+    }
+  });
+}
+
+/**
+ * The owner's grant of the project folder (Spec §1.14; CKC-26 AC-7, AC-8): record it, write the folder, and keep the
+ * folder out of what is read as the project's material. It is ProjectKeeper's output, written from the assets, so the
+ * Keeper never reads its own folder back as a project document; the scope item says so, and the owner can see it.
+ */
+export function grantProjectFolder(app: App, projectId: string, input: ProjectFolderAuthorizationInput) {
+  const project = app.project(projectId);
+  const store = app.store(project.id);
+  projectFolderPath(project, input.path);
+  const authorization = grantProjectFolderAuthorization(store, project, input);
+  // Excluded before anything is written (QC AW-2): a first write that fails part way must not leave the folder to be read
+  // back as project material once a later write succeeds.
+  excludeProjectFolder(app, project.id, authorization.projectFolder!.path, authorization.id);
+  const sync = syncProjectFolder(store, project);
+  return { authorization: store.authorizations.get(authorization.id), sync };
+}
+
+/** What the authorization allows, in one sentence: fixed interface text, shown beside the control on the Keeper page. */
+export const PROJECT_FOLDER_ALLOWS = 'With this authorization the Keeper maintains one folder of its own inside the project — projectkeeper/, unless you name another — and makes commits that contain only that folder; it never pushes, and it changes no other file of the project.';
+
+/** The folder a grant uses when the owner names no other, relative to the project root. */
+export const PROJECT_FOLDER_USUAL = 'projectkeeper';
+
+/** The project-folder authorization as the Keeper page shows it: what it allows, whether it stands, and what it did. */
+export interface ProjectFolderState {
+  readonly allows: string;
+  readonly granted: boolean;
+  /** The authorization in force; `Withdraw` revokes this one. */
+  readonly authorizationId: string | null;
+  /** The folder in force; without a grant, the folder of the last grant that was withdrawn, if any. */
+  readonly path: string | null;
+  /** The folder name a new grant starts from, relative to the project root: the last grant's folder, else `projectkeeper`. */
+  readonly usual: string;
+  readonly commits: boolean;
+  readonly grantedAt: string | null;
+  readonly lastWrite: { readonly at: string; readonly commit: string | null } | null;
+  /** When the last grant was withdrawn; null while one stands or when none was ever given. */
+  readonly withdrawnAt: string | null;
+  /** Whether `path` is in the project now: a withdrawal leaves the folder where it is. */
+  readonly exists: boolean;
+}
+
+export function projectFolderState(app: App, projectId: string): ProjectFolderState {
+  const all = app.store(projectId).authorizations.filter((a) => a.projectFolder != null).sort((a, b) => a.at.localeCompare(b.at));
+  const active = all.filter((a) => !a.revokedAt).at(-1) ?? null;
+  const last = active ?? all.at(-1) ?? null;
+  const path = last?.projectFolder?.path ?? null;
+  return {
+    allows: PROJECT_FOLDER_ALLOWS, granted: active !== null, authorizationId: active?.id ?? null, path, usual: relativeToRoot(app.project(projectId).locations[0], path) ?? PROJECT_FOLDER_USUAL,
+    commits: last?.projectFolder?.commits ?? true, grantedAt: active?.at ?? null, lastWrite: last?.projectFolder?.lastWrite ?? null,
+    withdrawnAt: active ? null : last?.revokedAt ?? null, exists: path !== null && existsSync(path),
+  };
+}
+
+/** A folder inside the project as the owner names it: relative to the project's root, with forward slashes. */
+function relativeToRoot(location: string | undefined, path: string | null): string | null {
+  if (!location || !path) return null;
+  try {
+    const rel = relative(canonicalPath(location), path);
+    return rel && !isAbsolute(rel) && rel.split(sep)[0] !== '..' ? rel.split(sep).join('/') : null;
+  } catch { return null; }
+}
+
+/** The project folder as a scope item: Excluded, with the authorization it belongs to as its reason. */
+export function excludeProjectFolder(app: App, projectId: string, path: string, authorizationId: string): void {
+  app.addScopeItem(projectId, {
+    path, category: 'Directory', relation: 'Excluded',
+    reason: `ProjectKeeper's project folder (${authorizationId}): written from the assets under the owner's authorization, not read as the project's material`,
+  });
+}

package/src/server/vendor.ts

@@ -0,0 +1,14 @@
+/**
+ * The node_modules the page's own scripts (cytoscape, dagre, cytoscape-dagre) are served from at `/vendor/`: the
+ * package's own in a clone, the one above it when ProjectKeeper is installed as a package and npm put its dependencies
+ * beside it.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export function vendorDir(appRoot: string): string {
+  for (let dir = appRoot; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'node_modules', 'cytoscape', 'package.json'))) return join(dir, 'node_modules');
+    if (dirname(dir) === dir) return join(appRoot, 'node_modules');
+  }
+}