Files
waggle-os/packages/server/src/local/routes/onboarding.ts
shumeiko.it f310333970 refactor(server): search memory through the contract in artifacts, agent runs, route proposals and onboarding (P1.5)
- Artifact Center related search lists personal and workspace memories
  through server.memory and finds related chat sessions in the session
  files (UF-034).
- /api/agent/run searches the requested workspace's memory, or personal
  memory when no known workspace is given.
- Executor briefs search only the workspace's own memory and leave out
  temporary memories in the query; route proposals no longer borrow a
  mind from the cache.
- Onboarding treats any personal memory as evidence of prior use.
- The service no longer creates personal.mind on a fresh install, and
  isFirstRun also looks for waggle.db.
2026-10-24 13:19:06 +02:00

82 lines
3.9 KiB
TypeScript

import type { FastifyPluginAsync } from 'fastify';
import fs from 'node:fs';
import path from 'node:path';
import { PERSONAL_SCOPE } from '@waggle/memory-contract';
/**
* P4 (UX-Refactor) — server-authoritative onboarding status.
*
* The FE's returning-user auto-complete used `GET /api/workspaces.length > 0`
* as its evidence — but buildLocalServer calls wsManager.ensureDefault() at
* boot, so a CLEAN install already has one workspace before the first render
* and a brand-new production user never saw the wizard (S4 founder flag,
* confirmed in P4). The workspace count can't distinguish "returning user"
* from "boot-seeded stub"; this surface can:
*
* - the completion FLAG (`<dataDir>/first-launch.flag` — the SAME file the
* Tauri `mark_first_launch_complete` command writes for default installs)
* is stamped by POST /api/onboarding/complete when any client finishes the
* wizard, and
* - LEGACY EVIDENCE covers installs that predate the flag: real usage in
* personal memory (any memory) or user-created workspaces beyond the
* seeded default.
*
* Fail direction: no flag + no evidence → completed:false → the wizard runs.
* Better to show it once too often than to silently skip it (same rule as the
* Rust command's IO-error fallback).
*/
const FLAG_FILE = 'first-launch.flag';
const PENDING_FILE = 'onboarding-pending.flag';
export const onboardingRoutes: FastifyPluginAsync = async (server) => {
const flagPath = (): string => path.join(server.localConfig.dataDir, FLAG_FILE);
const pendingPath = (): string => path.join(server.localConfig.dataDir, PENDING_FILE);
// Legacy-evidence is only consulted ONCE per dataDir. The first status call
// that finds no flag and no evidence stamps a durable PENDING marker — from
// then on, only explicit completion flips the status. Without the latch,
// the wizard's own pre-completion writes count as "evidence" (step 1's
// PUT /api/profile writes a 'User identity:' memory; C33 import writes
// memories; workspace-create makes list().length > 1) — and so do
// background writes, with zero user interaction. Any of those
// plus a lost localStorage (fresh WebView profile on reinstall, site-data
// clear) would silently skip the wizard for a user who never finished it —
// the exact failure direction this surface exists to prevent (review P4,
// onboarding-logic findings 1/6/11/13).
server.get('/api/onboarding/status', async () => {
if (fs.existsSync(flagPath())) {
return { completed: true, source: 'flag' };
}
if (fs.existsSync(pendingPath())) {
return { completed: false, source: 'pending' };
}
try {
if ((await server.memory.list({ scopes: [PERSONAL_SCOPE], limit: 1 })).length > 0) {
return { completed: true, source: 'legacy-evidence' };
}
} catch { /* memory unavailable → not evidence of prior use */ }
try {
if (server.workspaceManager.list().length > 1) {
return { completed: true, source: 'legacy-evidence' };
}
} catch { /* manager unavailable → not evidence */ }
// Un-onboarded dataDir identified — latch it so later wizard/system
// writes can never masquerade as a returning user.
try {
fs.mkdirSync(server.localConfig.dataDir, { recursive: true });
fs.writeFileSync(pendingPath(), new Date().toISOString());
} catch { /* latch failed → next call re-evaluates; fail-open to wizard */ }
return { completed: false, source: 'none' };
});
// Idempotent completion stamp. The wizard's complete() fires this alongside
// the Tauri filesystem flag (which only covers default ~/.waggle installs).
server.post('/api/onboarding/complete', async () => {
fs.mkdirSync(server.localConfig.dataDir, { recursive: true });
fs.writeFileSync(flagPath(), new Date().toISOString());
try { fs.unlinkSync(pendingPath()); } catch { /* never stamped — fine */ }
return { completed: true };
});
};