diff --git a/.changeset/session-store.md b/.changeset/session-store.md new file mode 100644 index 0000000..9743241 --- /dev/null +++ b/.changeset/session-store.md @@ -0,0 +1,7 @@ +--- +'@archwise/application': patch +'@archwise/storage': patch +'@archwise/cli': patch +--- + +Add the local session store. Discovered graphs are recorded as `archwise.graph` revisions in a SQLite store outside the project. The store has migrations, backups and corruption recovery. The CLI gains a protected session API, `--sessions` and `--no-store`. The Studio session UI follows separately. diff --git a/.dependency-cruiser.mjs b/.dependency-cruiser.mjs index 6c8abfe..37bc785 100644 --- a/.dependency-cruiser.mjs +++ b/.dependency-cruiser.mjs @@ -20,6 +20,15 @@ export default { from: { path: '^packages/application/src/' }, to: { pathNot: '^packages/(application|domain|schemas)/' }, }, + { + name: 'storage-inward-only', + severity: 'error', + from: { path: '^packages/storage/src/' }, + to: { + pathNot: '^packages/(storage|application|domain|schemas)/', + dependencyTypesNot: ['core'], + }, + }, { name: 'schemas-inward-only', severity: 'error', diff --git a/README.md b/README.md index 8918da3..56f68b9 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Archwise is a local-first, open-source workspace for discovering, understanding, explaining, and safely experimenting with software architecture. -> **Project status (`main`, pre-release):** local Alpha preview. Node package-manifest discovery, an evidence-backed package dependency graph, a protected loopback API, a Svelte 5/Svelte Flow Architecture Studio, a locally persisted Sandbox with versioned JSON import/export, and deterministic offline coaching questions are implemented. A deterministic **hypothetical Sandbox capacity simulation** is now available with visible assumptions; production-traffic observation, deep infrastructure discovery, multi-revision history, and AI interviewing remain future work. Versioned graph revision contracts (`archwise.graph` v1) exist in the core packages but are not yet wired into discovery. No package or npm CLI has been published. See the [roadmap status](docs/implementation-roadmap.md#current-state) for what is delivered, what is partial, and what comes next. +> **Project status (`main`, pre-release):** local Alpha preview. Node package-manifest discovery, an evidence-backed package dependency graph, a protected loopback API, a Svelte 5/Svelte Flow Architecture Studio, a locally persisted Sandbox with versioned JSON import/export, and deterministic offline coaching questions are implemented. A deterministic **hypothetical Sandbox capacity simulation** is now available with visible assumptions; production-traffic observation, deep infrastructure discovery, multi-revision history, and AI interviewing remain future work. Discovered graphs are recorded as versioned `archwise.graph` v1 revisions, and Sandbox sessions persist in a local SQLite store outside the project (`--sessions`; the Studio switches to it in the next increment). No package or npm CLI has been published. See the [roadmap status](docs/implementation-roadmap.md#current-state) for what is delivered, what is partial, and what comes next. ## Development @@ -37,6 +37,7 @@ The product starts from code already on a developer's machine. From a selected w - [Architecture and local data flow](docs/architecture.md) - [Automatic discovery and multi-repository workspaces](docs/discovery.md) - [Real graph, sandbox, and provenance model](docs/graph-and-sandbox.md) +- [Sessions and the local store](docs/sessions.md) - [Simulation model](docs/simulator.md) - [AI interviewer and coach](docs/ai-coach.md) - [Security and privacy](docs/security.md) @@ -47,6 +48,7 @@ The product starts from code already on a developer's machine. From a selected w - [Optional open-core business strategies](docs/business.md) - [Architecture decision](docs/decisions/0001-local-first-open-source.md) - [Browser workspace decision: Svelte Flow](docs/decisions/0005-svelte-flow-browser-workspace.md) +- [Local store decision: node:sqlite](docs/decisions/0006-local-store-node-sqlite.md) - [Alpha testing guide](docs/alpha-testing.md) - [Original README preserved as history](docs/history/README-saas-original.md) diff --git a/apps/cli/README.md b/apps/cli/README.md index 37b6c98..e95b06e 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -2,6 +2,8 @@ Argument parsing, the read-only Node package-manifest inventory, evidence-backed package graph construction and the protected loopback HTTP server that serves the Studio (`--json`, `--graph`, `--serve`, `--no-open`). It never executes or imports code from the inspected project. +With `--serve`, it also records the discovered graph as an `archwise.graph` revision and serves the protected session API (see `docs/sessions.md`). `--sessions` lists saved sessions, and `--no-store` disables the local store. + Inventory, graph and server logic live here temporarily during the Alpha; ADR 0005 records the planned extraction into discovery, domain/schemas and server packages. Source lives in `src/`. Tests ship alongside the package and run with `pnpm --filter @archwise/cli test`. Public package exports (where applicable) point only to built `dist/index.js` and its declarations. diff --git a/apps/cli/package.json b/apps/cli/package.json index d0abfcb..bab442e 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -20,5 +20,11 @@ }, "bin": { "archwise": "dist/bin.js" + }, + "dependencies": { + "@archwise/application": "workspace:*", + "@archwise/domain": "workspace:*", + "@archwise/schemas": "workspace:*", + "@archwise/storage": "workspace:*" } } diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts index 70be8c9..9606a65 100644 --- a/apps/cli/src/bin.ts +++ b/apps/cli/src/bin.ts @@ -2,11 +2,14 @@ import { readFileSync } from 'node:fs'; import { spawn } from 'node:child_process'; import { fileURLToPath } from 'node:url'; -import { resolve } from 'node:path'; +import { basename, resolve } from 'node:path'; +import { homedir } from 'node:os'; +import { resolveDataDir, StoreUnavailableError } from '@archwise/storage'; import { inspectWorkspace } from './inventory.js'; import { buildArchitectureGraph } from './graph.js'; import { parseCli } from './index.js'; import { startLocalGraphServer } from './local-server.js'; +import { formatSessionList, prepareStore, storeUnavailableMessage } from './store-runtime.js'; const metadata: unknown = JSON.parse( readFileSync(new URL('../package.json', import.meta.url), 'utf8'), @@ -41,9 +44,31 @@ if (command.kind === 'output') { process.stderr.write(command.result.stderr); process.exitCode = command.result.exitCode; } else { + const dataDir = resolveDataDir(process.env, process.platform, homedir()); try { const result = await inspectWorkspace(command.path); - if (command.serve) { + const graph = buildArchitectureGraph(result); + const prepareRuntime = async (enabled: boolean) => { + const runtime = await prepareStore({ + enabled, + dataDir, + rootPath: result.root, + rootLabel: basename(result.root), + graph, + }); + for (const notice of runtime.notices) process.stderr.write(`${notice}\n`); + return runtime; + }; + if (command.sessions) { + const runtime = await prepareRuntime(true); + if (runtime.kind === 'ready') { + process.stdout.write(formatSessionList(runtime.service.list())); + runtime.store.close(); + } else { + process.exitCode = 1; + } + } else if (command.serve) { + const runtime = await prepareRuntime(command.store); const webDistPath = resolve(fileURLToPath(new URL('../../web/dist/', import.meta.url))); // CLI/API mode works before the browser bundle is built; serve assets if available. let assets: string | undefined; @@ -53,16 +78,21 @@ if (command.kind === 'output') { } catch { process.stderr.write('Browser assets are not built; serving JSON API only.\n'); } - const server = await startLocalGraphServer( - buildArchitectureGraph(result), - assets ? { webDistPath: assets } : {}, - ); + const server = await startLocalGraphServer(graph, { + ...(assets ? { webDistPath: assets } : {}), + sessions: runtime.kind === 'ready' ? runtime.service : null, + }); process.stdout.write(`Archwise API listening at ${server.address}\n`); process.stdout.write(`Local session URL: ${server.bootstrapUrl}\n`); + process.stdout.write( + runtime.kind === 'ready' + ? 'Local session store ready (outside the project). List saved sessions with --sessions.\n' + : 'Local session store disabled for this run.\n', + ); process.stdout.write('Press Ctrl+C to stop.\n'); if (command.open && assets) openBrowser(server.bootstrapUrl); } else if (command.graph) { - process.stdout.write(`${JSON.stringify(buildArchitectureGraph(result), null, 2)}\n`); + process.stdout.write(`${JSON.stringify(graph, null, 2)}\n`); } else if (command.json) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); } else { @@ -74,13 +104,18 @@ if (command.kind === 'output') { } for (const warning of result.diagnostics) process.stderr.write(`Warning: ${warning}\n`); process.stdout.write( - 'Run with --graph for graph JSON. Browser Studio is not yet integrated.\n', + 'Run with --graph for graph JSON, --serve to open the local Studio, or --sessions to list saved sessions.\n', ); } } catch (error) { - process.stderr.write( - `Unable to inspect workspace: ${error instanceof Error ? error.message : 'Unknown error'}\n`, - ); - process.exitCode = 1; + if (error instanceof StoreUnavailableError) { + process.stderr.write(`${storeUnavailableMessage(error.reason, dataDir)}\n`); + process.exitCode = 2; + } else { + process.stderr.write( + `Unable to inspect workspace: ${error instanceof Error ? error.message : 'Unknown error'}\n`, + ); + process.exitCode = 1; + } } } diff --git a/apps/cli/src/http.ts b/apps/cli/src/http.ts new file mode 100644 index 0000000..d8d4171 --- /dev/null +++ b/apps/cli/src/http.ts @@ -0,0 +1,8 @@ +import type { ServerResponse } from 'node:http'; + +/** JSON response helper shared by the loopback server routes. */ +export function json(res: ServerResponse, status: number, payload: unknown, head = false): void { + res.statusCode = status; + res.setHeader('Content-Type', 'application/json; charset=utf-8'); + res.end(head ? undefined : JSON.stringify(payload)); +} diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts index 716da7b..96a1557 100644 --- a/apps/cli/src/index.ts +++ b/apps/cli/src/index.ts @@ -13,6 +13,10 @@ export type CliCommand = readonly graph: boolean; readonly serve: boolean; readonly open: boolean; + /** List saved sessions for the workspace instead of inspecting. */ + readonly sessions: boolean; + /** Use the local session store (disabled by --no-store). */ + readonly store: boolean; }; /** Parse arguments without touching the filesystem or executing project code. */ @@ -26,8 +30,10 @@ export function parseCli(args: readonly string[], version = 'development'): CliC result: { exitCode: 0, stdout: - 'Usage: archwise [--path DIRECTORY] [--json | --graph | --serve] [--no-open] [--help | --version]\n' + - 'Read-only inventory of local Node.js package manifests. --graph emits a deterministic evidence-backed graph.\n', + 'Usage: archwise [--path DIRECTORY] [--json | --graph | --sessions | --serve [--no-open] [--no-store]] [--help | --version]\n' + + 'Read-only inventory of local Node.js package manifests. --graph emits a deterministic evidence-backed graph.\n' + + '--sessions lists saved Sandbox sessions for this project. --serve opens the local Studio and records\n' + + 'the discovered graph in the local store outside the project; --no-store disables the store.\n', stderr: '', }, }; @@ -37,6 +43,8 @@ export function parseCli(args: readonly string[], version = 'development'): CliC let graph = false; let serve = false; let open = true; + let sessions = false; + let store = true; for (let i = 0; i < args.length; i++) { if (args[i] === '--path' && args[i + 1] && !args[i + 1]!.startsWith('--')) { path = args[++i]!; @@ -48,6 +56,10 @@ export function parseCli(args: readonly string[], version = 'development'): CliC serve = true; } else if (args[i] === '--no-open') { open = false; + } else if (args[i] === '--sessions') { + sessions = true; + } else if (args[i] === '--no-store') { + store = false; } else { return { kind: 'output', @@ -59,13 +71,13 @@ export function parseCli(args: readonly string[], version = 'development'): CliC }; } } - if (Number(json) + Number(graph) + Number(serve) > 1) { + if (Number(json) + Number(graph) + Number(serve) + Number(sessions) > 1) { return { kind: 'output', result: { exitCode: 2, stdout: '', - stderr: '--json, --graph and --serve are mutually exclusive.\n', + stderr: '--json, --graph, --sessions and --serve are mutually exclusive.\n', }, }; } @@ -75,7 +87,13 @@ export function parseCli(args: readonly string[], version = 'development'): CliC result: { exitCode: 2, stdout: '', stderr: '--no-open requires --serve.\n' }, }; } - return { kind: 'inspect', path, json, graph, serve, open }; + if (!serve && !store) { + return { + kind: 'output', + result: { exitCode: 2, stdout: '', stderr: '--no-store requires --serve.\n' }, + }; + } + return { kind: 'inspect', path, json, graph, serve, open, sessions, store }; } /** Kept as a pure CLI helper for compatibility with the existing CLI tests. */ diff --git a/apps/cli/src/local-server.ts b/apps/cli/src/local-server.ts index 540e237..e787c2d 100644 --- a/apps/cli/src/local-server.ts +++ b/apps/cli/src/local-server.ts @@ -3,7 +3,10 @@ import { randomBytes, timingSafeEqual } from 'node:crypto'; import { readFile, realpath, stat } from 'node:fs/promises'; import { extname, relative, resolve, sep } from 'node:path'; import type { AddressInfo } from 'node:net'; +import type { SessionService } from '@archwise/application'; import type { ArchitectureGraph } from './graph.js'; +import { json } from './http.js'; +import { handleSessionRoute, isSessionRoute } from './session-routes.js'; const HOST = '127.0.0.1'; const MAX_PATH_LENGTH = 2048; @@ -28,6 +31,8 @@ export interface LocalServer { } export interface ServerOptions { readonly webDistPath?: string; + /** Local session store; null or absent runs without persistence. */ + readonly sessions?: SessionService | null; } function equalSecret(value: string | undefined, secret: string): boolean { @@ -49,12 +54,6 @@ function securityHeaders(res: ServerResponse): void { ); } -function json(res: ServerResponse, status: number, payload: unknown, head = false): void { - res.statusCode = status; - res.setHeader('Content-Type', 'application/json; charset=utf-8'); - res.end(head ? undefined : JSON.stringify(payload)); -} - function authorized(req: IncomingMessage, secret: string): boolean { const auth = req.headers.authorization; if (auth?.startsWith('Bearer ') && equalSecret(auth.slice(7), secret)) return true; @@ -148,10 +147,6 @@ export async function startLocalGraphServer( return; } const head = req.method === 'HEAD'; - if (req.method !== 'GET' && !head) { - json(res, 405, { error: 'Method not allowed' }); - return; - } let url: URL; try { url = new URL(req.url, `http://${address}`); @@ -159,6 +154,11 @@ export async function startLocalGraphServer( json(res, 400, { error: 'Invalid URL' }); return; } + const sessionRoute = isSessionRoute(url.pathname); + if (req.method !== 'GET' && !head && !sessionRoute) { + json(res, 405, { error: 'Method not allowed' }); + return; + } if (url.pathname.startsWith('/session/')) { const submitted = url.pathname.slice('/session/'.length); if ( @@ -188,6 +188,13 @@ export async function startLocalGraphServer( json(res, 400, { error: 'Query parameters not supported' }, head); return; } + if (sessionRoute) { + await handleSessionRoute(req, res, url.pathname, { + sessions: options.sessions ?? null, + origin: `http://${address}`, + }); + return; + } if (url.pathname === '/api/v1/graph') { json(res, 200, graph, head); return; diff --git a/apps/cli/src/revision.ts b/apps/cli/src/revision.ts new file mode 100644 index 0000000..57f011e --- /dev/null +++ b/apps/cli/src/revision.ts @@ -0,0 +1,107 @@ +import { createHash } from 'node:crypto'; +import { LIMITS, type Diagnostic, type Evidence, type GraphRevision } from '@archwise/domain'; +import type { RevisionIds } from '@archwise/application'; +import type { ArchitectureGraph } from './graph.js'; + +export const MANIFEST_ANALYZER = { id: 'node-manifest', version: '1.0.0' } as const; +const REPOSITORY_ID = 'repo-root'; + +const shortHash = (text: string): string => + createHash('sha256').update(text, 'utf8').digest('hex').slice(0, 16); + +const DIAGNOSTIC_CODES: readonly [prefix: string, code: string][] = [ + ['Ambiguous package name', 'ambiguous-package-name'], + ['Unresolved dependency', 'unresolved-dependency'], +]; + +function diagnosticCode(message: string): string { + return ( + DIAGNOSTIC_CODES.find(([prefix]) => message.startsWith(prefix))?.[1] ?? 'inventory-warning' + ); +} + +function rootLabelOf(label: string): string { + const trimmed = Array.from(label).slice(0, LIMITS.label).join(''); + return trimmed.length > 0 ? trimmed : 'workspace'; +} + +/** + * Maps the CLI's package graph to an `archwise.graph` v1 revision. Package manifests become + * `module` nodes and declared internal dependencies become `depends-on` edges, each backed by + * the manifest that declares it. Identifiers derive deterministically from relative paths. + * Diagnostic text stays in the Studio view; the revision carries stable codes only. + */ +export function buildGraphRevision( + graph: ArchitectureGraph, + rootLabel: string, + ids: RevisionIds, +): GraphRevision { + const evidence = new Map(); + const addEvidence = (rule: 'package-manifest' | 'package-dependency', path: string): string => { + const id = `ev-${shortHash(`${rule === 'package-manifest' ? 'manifest' : 'dependency'}:${path}`)}`; + evidence.set(id, { + id, + repositoryId: REPOSITORY_ID, + analyzerId: MANIFEST_ANALYZER.id, + analyzerVersion: MANIFEST_ANALYZER.version, + ruleId: rule, + path, + lines: null, + }); + return id; + }; + + const nodeIds = new Map(); + const nodes = graph.nodes.map((node) => { + const path = node.evidence[0].path; + const id = `mod-${shortHash(path)}`; + nodeIds.set(node.id, id); + return { + id, + kind: 'module' as const, + label: node.label, + repositoryId: REPOSITORY_ID, + confidence: { level: 'observed' as const, reasons: ['manifest-declared'] }, + evidenceIds: [addEvidence('package-manifest', path)], + }; + }); + + const edges = graph.edges.map((edge) => ({ + id: `dep-${shortHash(edge.id)}`, + kind: 'depends-on' as const, + sourceId: nodeIds.get(edge.source) ?? edge.source, + targetId: nodeIds.get(edge.target) ?? edge.target, + confidence: { level: 'observed' as const, reasons: ['dependency-declared'] }, + evidenceIds: [addEvidence('package-dependency', edge.evidence[0].path)], + })); + + const codes = [...new Set(graph.diagnostics.map(diagnosticCode))].sort(); + const diagnostics: Diagnostic[] = codes.map((code) => ({ + id: `diag-${code}`, + severity: 'warning', + code, + references: [], + })); + const status = graph.diagnostics.length === 0 ? 'complete' : 'partial'; + + return { + id: ids.revisionId, + workspaceId: ids.workspaceId, + parentRevisionId: ids.parentRevisionId, + createdAt: ids.createdAt, + status, + repositories: [{ id: REPOSITORY_ID, label: rootLabelOf(rootLabel) }], + coverage: [ + { + repositoryId: REPOSITORY_ID, + analyzerId: MANIFEST_ANALYZER.id, + analyzerVersion: MANIFEST_ANALYZER.version, + status, + }, + ], + evidence: [...evidence.values()], + nodes, + edges, + diagnostics, + }; +} diff --git a/apps/cli/src/session-routes.ts b/apps/cli/src/session-routes.ts new file mode 100644 index 0000000..7ddcf9e --- /dev/null +++ b/apps/cli/src/session-routes.ts @@ -0,0 +1,141 @@ +import type { IncomingMessage, ServerResponse } from 'node:http'; +import type { ServiceError, ServiceResult, SessionService } from '@archwise/application'; +import { json } from './http.js'; + +const PREFIX = '/api/v1/sessions'; +const SESSION_ID = /^ses-[0-9a-f]{24}$/; +export const MAX_BODY_BYTES = 300_000; + +const ERROR_STATUS: Readonly> = { + 'not-found': 404, + 'too-large': 413, + 'invalid-sandbox': 422, + 'invalid-label': 422, +}; + +export function isSessionRoute(pathname: string): boolean { + return pathname === PREFIX || pathname.startsWith(`${PREFIX}/`); +} + +class BodyTooLarge extends Error {} + +/** Reads a request body, aborting once the byte limit is exceeded. */ +async function readBody(req: IncomingMessage): Promise { + const declared = Number(req.headers['content-length'] ?? 0); + if (declared > MAX_BODY_BYTES) throw new BodyTooLarge(); + const chunks: Buffer[] = []; + let size = 0; + for await (const chunk of req) { + const buffer = chunk as Buffer; + size += buffer.byteLength; + if (size > MAX_BODY_BYTES) throw new BodyTooLarge(); + chunks.push(buffer); + } + return Buffer.concat(chunks).toString('utf8'); +} + +function send(res: ServerResponse, result: ServiceResult, map: (value: T) => unknown): void { + if (result.ok) json(res, 200, map(result.value)); + else json(res, ERROR_STATUS[result.error], { error: result.error }); +} + +const notFound = (res: ServerResponse): void => json(res, 404, { error: 'Not found' }); + +/** + * Session API behind the existing capability check. Mutations additionally require a + * same-origin `Origin` header and a JSON content type. Responses never contain filesystem + * paths and never echo identifiers or bodies that were rejected. + */ +export async function handleSessionRoute( + req: IncomingMessage, + res: ServerResponse, + pathname: string, + context: { readonly sessions: SessionService | null; readonly origin: string }, +): Promise { + const method = req.method === 'HEAD' ? 'GET' : (req.method ?? 'GET'); + const { sessions } = context; + + if (pathname === `${PREFIX}/current` && method === 'GET') { + json( + res, + 200, + sessions + ? { ...sessions.current(), storeEnabled: true } + : { id: null, persisted: false, storeEnabled: false }, + ); + return; + } + if (!sessions) { + notFound(res); + return; + } + if (pathname === PREFIX && method === 'GET') { + json(res, 200, { sessions: sessions.list() }); + return; + } + + const [id, action, ...rest] = pathname.slice(PREFIX.length + 1).split('/'); + if (!id || !SESSION_ID.test(id) || rest.length > 0) { + notFound(res); + return; + } + + const mutating = method !== 'GET'; + if (mutating && req.headers.origin !== context.origin) { + json(res, 403, { error: 'Same-origin request required' }); + return; + } + const needsBody = (action === 'sandbox' && method === 'PUT') || (!action && method === 'PATCH'); + let body = ''; + if (needsBody) { + if (!req.headers['content-type']?.toLowerCase().startsWith('application/json')) { + json(res, 415, { error: 'Content-Type must be application/json' }); + return; + } + try { + body = await readBody(req); + } catch (error) { + if (error instanceof BodyTooLarge) { + json(res, 413, { error: 'too-large' }); + req.resume(); + return; + } + throw error; + } + } + + const withView = (detail: { view: string }) => ({ + ...detail, + view: JSON.parse(detail.view) as unknown, + }); + + if (!action && method === 'GET') return send(res, sessions.get(id), withView); + if (action === 'resume' && method === 'POST') return send(res, sessions.resume(id), withView); + if (action === 'sandbox' && method === 'PUT') { + return send(res, sessions.saveSandbox(id, body), (summary) => summary); + } + if (!action && method === 'PATCH') { + let label: unknown; + try { + label = (JSON.parse(body) as { label?: unknown }).label; + } catch { + label = undefined; + } + if (typeof label !== 'string') { + json(res, 422, { error: 'invalid-label' }); + return; + } + return send(res, sessions.rename(id, label), (summary) => summary); + } + if (!action && method === 'DELETE') { + const result = sessions.delete(id); + if (result.ok) { + res.statusCode = 204; + res.end(); + } else { + json(res, ERROR_STATUS[result.error], { error: result.error }); + } + return; + } + json(res, 405, { error: 'Method not allowed' }); +} diff --git a/apps/cli/src/store-runtime.ts b/apps/cli/src/store-runtime.ts new file mode 100644 index 0000000..e50b865 --- /dev/null +++ b/apps/cli/src/store-runtime.ts @@ -0,0 +1,122 @@ +import { createHash, randomBytes } from 'node:crypto'; +import { existsSync, realpathSync } from 'node:fs'; +import { dirname, isAbsolute, relative, resolve } from 'node:path'; +import { RevisionInvalidError, SessionService, type SessionSummary } from '@archwise/application'; +import { openStore, type OpenedStore, type StoreUnavailableReason } from '@archwise/storage'; +import type { ArchitectureGraph } from './graph.js'; +import { buildGraphRevision } from './revision.js'; + +export type StoreRuntime = + | { readonly kind: 'disabled'; readonly notices: readonly string[] } + | { + readonly kind: 'ready'; + readonly service: SessionService; + readonly store: OpenedStore; + readonly notices: readonly string[]; + }; + +export interface PrepareStoreOptions { + readonly enabled: boolean; + readonly dataDir: string; + readonly rootPath: string; + readonly rootLabel: string; + readonly graph: ArchitectureGraph; +} + +/** + * Opens the local store and records this discovery run. Throws `StoreUnavailableError` for + * newer-schema, failed-migration and unwritable stores; the caller exits with code 2. + */ +/** Resolves symlinks through the nearest existing ancestor, for paths that may not exist yet. */ +function canonical(path: string): string { + let current = resolve(path); + const missing: string[] = []; + while (!existsSync(current) && dirname(current) !== current) { + missing.unshift(current.slice(dirname(current).length + 1)); + current = dirname(current); + } + return resolve(realpathSync(current), ...missing); +} + +/** True when `child` is `parent` or lies beneath it. */ +export function isWithin(child: string, parent: string): boolean { + const rel = relative(canonical(parent), canonical(child)); + return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)); +} + +export async function prepareStore(options: PrepareStoreOptions): Promise { + if (!options.enabled) return { kind: 'disabled', notices: [] }; + if (isWithin(options.dataDir, options.rootPath)) { + return { + kind: 'disabled', + notices: [ + 'The local store directory is inside the analyzed project; sessions are not saved in this run. Set ARCHWISE_DATA_DIR to a directory outside the project.', + ], + }; + } + const store = await openStore(options.dataDir); + const notices: string[] = []; + if (store.quarantinedPath) { + notices.push( + `Store file was corrupt; moved to ${store.quarantinedPath}. Started a fresh store.`, + ); + } + if (store.backupPath) notices.push(`Store migrated; backup at ${store.backupPath}.`); + try { + const opened = SessionService.open( + { + store, + clock: { now: () => new Date().toISOString() }, + ids: { next: (prefix) => `${prefix}-${randomBytes(12).toString('hex')}` }, + digest: { sha256Hex: (text) => createHash('sha256').update(text, 'utf8').digest('hex') }, + }, + { + rootPath: options.rootPath, + view: JSON.stringify(options.graph), + viewIdentity: JSON.stringify({ ...options.graph, inspectedEntries: 0 }), + build: (ids) => buildGraphRevision(options.graph, options.rootLabel, ids), + }, + ); + if (!opened.ok) throw new Error(opened.error); + return { kind: 'ready', service: opened.value, store, notices }; + } catch (error) { + store.close(); + if (error instanceof RevisionInvalidError) { + return { + kind: 'disabled', + notices: [ + ...notices, + 'The discovered graph could not be recorded as a revision; sessions are not saved in this run.', + ], + }; + } + throw error; + } +} + +export function storeUnavailableMessage(reason: StoreUnavailableReason, dataDir: string): string { + switch (reason) { + case 'newer-schema': + return `The local store in ${dataDir} was written by a newer Archwise. Upgrade Archwise, or run with --no-store.`; + case 'migration-failed': + return `Upgrading the local store in ${dataDir} failed; the file was left unchanged. Please report a bug, and run with --no-store meanwhile.`; + case 'unwritable': + return `The local store directory ${dataDir} is not writable. Fix its permissions, or set ARCHWISE_DATA_DIR to a writable directory.`; + } +} + +export function formatSessionList(sessions: readonly SessionSummary[]): string { + if (sessions.length === 0) return 'No saved sessions for this project.\n'; + return sessions + .map((session) => { + const flags = [session.hasSnapshots ? 'A/B' : '', session.baseIsCurrent ? '' : 'changed'] + .filter(Boolean) + .join(' '); + const count = `${session.componentCount} component${session.componentCount === 1 ? '' : 's'}`; + return [session.updatedAt, session.label, count, flags, session.id] + .filter(Boolean) + .join(' '); + }) + .join('\n') + .concat('\n'); +} diff --git a/apps/cli/tests/cli.test.ts b/apps/cli/tests/cli.test.ts index 75e17e6..bb0b3bb 100644 --- a/apps/cli/tests/cli.test.ts +++ b/apps/cli/tests/cli.test.ts @@ -9,6 +9,8 @@ test('defaults to read-only inspection of current directory', () => { graph: false, serve: false, open: true, + sessions: false, + store: true, }); }); @@ -20,6 +22,8 @@ test('accepts a workspace path and graph output', () => { graph: true, serve: false, open: true, + sessions: false, + store: true, }); }); @@ -41,5 +45,24 @@ test('prints help and rejects unsupported or contradictory options', () => { graph: false, serve: true, open: false, + sessions: false, + store: true, }); }); + +test('lists saved sessions and controls the local store', () => { + expect(parseCli(['--sessions'])).toMatchObject({ kind: 'inspect', sessions: true, serve: false }); + expect(parseCli(['--serve', '--no-store'])).toMatchObject({ serve: true, store: false }); + expect(runCli(['--sessions', '--serve']).exitCode).toBe(2); + expect(runCli(['--sessions', '--graph']).exitCode).toBe(2); + expect(runCli(['--no-store']).exitCode).toBe(2); + expect(runCli(['--help']).stdout).toContain('--sessions'); + expect(runCli(['--help']).stdout).toContain('--no-store'); +}); + +test('help does not claim the Studio already saves sessions', () => { + const help = runCli(['--help']).stdout; + expect(help).not.toContain('saves\nSandbox sessions'); + expect(help).not.toMatch(/saves Sandbox sessions/); + expect(help).toContain('local store'); +}); diff --git a/apps/cli/tests/revision.test.ts b/apps/cli/tests/revision.test.ts new file mode 100644 index 0000000..38ffa8b --- /dev/null +++ b/apps/cli/tests/revision.test.ts @@ -0,0 +1,113 @@ +import { createRevision, isValidId } from '@archwise/domain'; +import { serializeGraphRevision } from '@archwise/schemas'; +import { expect, test } from 'vitest'; +import type { ArchitectureGraph } from '../src/graph.js'; +import { buildGraphRevision } from '../src/revision.js'; + +const ids = { + revisionId: 'rev-1', + workspaceId: 'ws-1', + parentRevisionId: null, + createdAt: '2026-11-16T00:00:00.000Z', +}; + +const node = (path: string, label: string) => ({ + id: `package:${path}`, + type: 'package' as const, + label, + framework: null, + origin: 'discovered' as const, + evidence: [{ path, kind: 'package-manifest' as const }] as const, +}); + +const graph: ArchitectureGraph = { + version: 1, + nodes: [ + node('package.json', 'root'), + node('apps/web/package.json', '@demo/web'), + node('packages/core/package.json', '@demo/core'), + ], + edges: [ + { + id: 'dependency:package:apps/web/package.json->package:packages/core/package.json', + type: 'declared-dependency', + source: 'package:apps/web/package.json', + target: 'package:packages/core/package.json', + origin: 'discovered', + evidence: [{ path: 'apps/web/package.json', kind: 'package-dependency' }], + }, + ], + diagnostics: ['Ambiguous package name: dup (a/package.json, b/package.json)'], + inspectedEntries: 12, +}; + +test('maps packages and declared dependencies to a valid partial revision', () => { + const revision = buildGraphRevision(graph, 'demo-project', ids); + const created = createRevision(revision); + expect(created.ok).toBe(true); + expect(revision.status).toBe('partial'); + expect(revision.coverage).toEqual([ + { + repositoryId: 'repo-root', + analyzerId: 'node-manifest', + analyzerVersion: '1.0.0', + status: 'partial', + }, + ]); + expect(revision.repositories).toEqual([{ id: 'repo-root', label: 'demo-project' }]); + expect(revision.nodes.map((n) => n.kind)).toEqual(['module', 'module', 'module']); + expect(revision.nodes.map((n) => n.label).sort()).toEqual(['@demo/core', '@demo/web', 'root']); + expect(revision.edges).toHaveLength(1); + expect(revision.edges[0]!.kind).toBe('depends-on'); + expect(revision.diagnostics.map((d) => d.code)).toEqual(['ambiguous-package-name']); +}); + +test('edges point at the nodes derived from the same manifests', () => { + const revision = buildGraphRevision(graph, 'demo', ids); + const byLabel = new Map(revision.nodes.map((n) => [n.label, n.id])); + expect(revision.edges[0]!.sourceId).toBe(byLabel.get('@demo/web')); + expect(revision.edges[0]!.targetId).toBe(byLabel.get('@demo/core')); +}); + +test('identifiers are domain-valid and stable', () => { + const first = buildGraphRevision(graph, 'demo', ids); + const second = buildGraphRevision(graph, 'demo', ids); + for (const id of [...first.nodes, ...first.edges, ...first.evidence].map((r) => r.id)) { + expect(isValidId(id)).toBe(true); + } + expect(serializeGraphRevision(first)).toEqual(serializeGraphRevision(second)); +}); + +test('an empty graph is a valid complete revision', () => { + const revision = buildGraphRevision( + { version: 1, nodes: [], edges: [], diagnostics: [], inspectedEntries: 0 }, + 'empty', + ids, + ); + expect(revision.status).toBe('complete'); + expect(createRevision(revision).ok).toBe(true); +}); + +test('diagnostic categories map to stable codes, once each', () => { + const revision = buildGraphRevision( + { + ...graph, + diagnostics: [ + 'Unresolved dependency x in a/package.json: multiple workspace matches', + 'Unresolved dependency y in b/package.json: multiple workspace matches', + 'Inventory truncated after 3000 entries', + ], + }, + 'demo', + ids, + ); + expect(revision.diagnostics.map((d) => d.code).sort()).toEqual([ + 'inventory-warning', + 'unresolved-dependency', + ]); +}); + +test('long root labels are trimmed to 256 code points', () => { + const revision = buildGraphRevision(graph, '🚀'.repeat(300), ids); + expect([...revision.repositories[0]!.label]).toHaveLength(256); +}); diff --git a/apps/cli/tests/session-api.test.ts b/apps/cli/tests/session-api.test.ts new file mode 100644 index 0000000..6de2014 --- /dev/null +++ b/apps/cli/tests/session-api.test.ts @@ -0,0 +1,202 @@ +import { createMemoryStore, SessionService, type IdGenerator } from '@archwise/application'; +import { afterEach, expect, test } from 'vitest'; +import type { ArchitectureGraph } from '../src/graph.js'; +import { startLocalGraphServer, type LocalServer } from '../src/local-server.js'; +import { buildGraphRevision } from '../src/revision.js'; + +const graph: ArchitectureGraph = { + version: 1, + nodes: [], + edges: [], + diagnostics: [], + inspectedEntries: 0, +}; + +const hexIds = (): IdGenerator => { + let n = 0; + return { next: (prefix) => `${prefix}-${(++n).toString(16).padStart(24, '0')}` }; +}; + +function service(): SessionService { + let second = 0; + const opened = SessionService.open( + { + store: createMemoryStore(), + clock: { now: () => new Date(Date.UTC(2026, 10, 16, 0, 0, second++)).toISOString() }, + ids: hexIds(), + digest: { sha256Hex: (text) => text }, + }, + { + rootPath: '/secret/absolute/root', + view: JSON.stringify(graph), + viewIdentity: JSON.stringify(graph), + build: (ids) => buildGraphRevision(graph, 'root', ids), + }, + ); + if (!opened.ok) throw new Error(opened.error); + return opened.value; +} + +const sandbox = (components = 1) => + JSON.stringify({ + format: 'archwise-sandbox', + version: 1, + projectSignature: 'sig', + nodes: Array.from({ length: components }, (_, i) => ({ id: `sandbox-${i}` })), + connections: [], + draft: { savedA: null, savedB: null }, + }); + +let server: LocalServer | null = null; +afterEach(async () => { + await server?.close(); + server = null; +}); + +async function start(sessions: SessionService | null = service()) { + server = await startLocalGraphServer(graph, { sessions }); + const bootstrap = await fetch(server.bootstrapUrl, { redirect: 'manual' }); + const cookie = bootstrap.headers.get('set-cookie')!.split(';')[0]!; + const call = (path: string, init: RequestInit & { json?: boolean } = {}) => + fetch(`${server!.address}${path}`, { + ...init, + headers: { + cookie, + ...(init.method && init.method !== 'GET' ? { origin: server!.address } : {}), + ...(init.body !== undefined ? { 'content-type': 'application/json' } : {}), + ...(init.headers as Record | undefined), + }, + }); + return { call, address: server.address }; +} + +test('session routes require the session capability', async () => { + server = await startLocalGraphServer(graph, { sessions: service() }); + for (const path of ['/api/v1/sessions/current', '/api/v1/sessions']) { + expect((await fetch(`${server.address}${path}`)).status).toBe(401); + } +}); + +test('a reserved session is persisted on first save and then listed', async () => { + const { call } = await start(); + const current = (await (await call('/api/v1/sessions/current')).json()) as { + id: string; + persisted: boolean; + storeEnabled: boolean; + }; + expect(current).toMatchObject({ persisted: false, storeEnabled: true }); + expect((await call(`/api/v1/sessions/${current.id}`)).status).toBe(404); + + const saved = await call(`/api/v1/sessions/${current.id}/sandbox`, { + method: 'PUT', + body: sandbox(2), + }); + expect(saved.status).toBe(200); + expect(await saved.json()).toMatchObject({ id: current.id, componentCount: 2 }); + + const list = (await (await call('/api/v1/sessions')).json()) as { sessions: { id: string }[] }; + expect(list.sessions.map((s) => s.id)).toEqual([current.id]); + + const detail = await call(`/api/v1/sessions/${current.id}`); + expect(detail.status).toBe(200); + const body = (await detail.json()) as { sandbox: string; view: unknown; baseIsCurrent: boolean }; + expect(body.sandbox).toBe(sandbox(2)); + expect(body.view).toEqual(graph); + expect(body.baseIsCurrent).toBe(true); +}); + +test('rename, resume and delete', async () => { + const { call } = await start(); + const { id } = (await (await call('/api/v1/sessions/current')).json()) as { id: string }; + await call(`/api/v1/sessions/${id}/sandbox`, { method: 'PUT', body: sandbox() }); + + const renamed = await call(`/api/v1/sessions/${id}`, { + method: 'PATCH', + body: JSON.stringify({ label: 'Cache experiment' }), + }); + expect(renamed.status).toBe(200); + expect(await renamed.json()).toMatchObject({ label: 'Cache experiment' }); + + const badLabel = await call(`/api/v1/sessions/${id}`, { + method: 'PATCH', + body: JSON.stringify({ label: '' }), + }); + expect(badLabel.status).toBe(422); + expect(await badLabel.json()).toEqual({ error: 'invalid-label' }); + + const resumed = await call(`/api/v1/sessions/${id}/resume`, { method: 'POST' }); + expect(resumed.status).toBe(200); + + expect((await call(`/api/v1/sessions/${id}`, { method: 'DELETE' })).status).toBe(204); + expect((await call(`/api/v1/sessions/${id}`)).status).toBe(404); + const current = (await (await call('/api/v1/sessions/current')).json()) as { id: string }; + expect(current.id).not.toBe(id); +}); + +test('invalid sandbox payloads are rejected with stable codes', async () => { + const { call } = await start(); + const { id } = (await (await call('/api/v1/sessions/current')).json()) as { id: string }; + const invalid = await call(`/api/v1/sessions/${id}/sandbox`, { method: 'PUT', body: '{}' }); + expect(invalid.status).toBe(422); + expect(await invalid.json()).toEqual({ error: 'invalid-sandbox' }); + + const tooLarge = await call(`/api/v1/sessions/${id}/sandbox`, { + method: 'PUT', + body: ' '.repeat(300_001), + }); + expect(tooLarge.status).toBe(413); +}); + +test('mutations require same-origin requests with JSON bodies', async () => { + const { call, address } = await start(); + const { id } = (await (await call('/api/v1/sessions/current')).json()) as { id: string }; + const noOrigin = await call(`/api/v1/sessions/${id}/sandbox`, { + method: 'PUT', + body: sandbox(), + headers: { origin: '' }, + }); + expect(noOrigin.status).toBe(403); + + const wrongType = await call(`/api/v1/sessions/${id}/sandbox`, { + method: 'PUT', + body: sandbox(), + headers: { 'content-type': 'text/plain', origin: address }, + }); + expect(wrongType.status).toBe(415); +}); + +test.each(['/api/v1/sessions/..%2F..%2Fetc', `/api/v1/sessions/ses-${'a'.repeat(200)}`])( + 'path-like or oversized ids are 404 without echo: %s', + async (path) => { + const { call } = await start(); + const response = await call(path); + expect(response.status).toBe(404); + const text = await response.text(); + expect(text).not.toContain('etc'); + expect(text).not.toContain('aaaaaaaa'); + }, +); + +test('responses never contain the absolute workspace root', async () => { + const { call } = await start(); + const { id } = (await (await call('/api/v1/sessions/current')).json()) as { id: string }; + await call(`/api/v1/sessions/${id}/sandbox`, { method: 'PUT', body: sandbox() }); + for (const path of ['/api/v1/sessions/current', '/api/v1/sessions', `/api/v1/sessions/${id}`]) { + expect(await (await call(path)).text()).not.toContain('/secret/absolute/root'); + } +}); + +test('without a store the API reports it is disabled', async () => { + const { call } = await start(null); + expect(await (await call('/api/v1/sessions/current')).json()).toEqual({ + id: null, + persisted: false, + storeEnabled: false, + }); + expect((await call('/api/v1/sessions')).status).toBe(404); +}); + +test('non-session routes still reject mutating methods', async () => { + const { call } = await start(); + expect((await call('/api/v1/graph', { method: 'POST' })).status).toBe(405); +}); diff --git a/apps/cli/tests/store-runtime.test.ts b/apps/cli/tests/store-runtime.test.ts new file mode 100644 index 0000000..d7e2e88 --- /dev/null +++ b/apps/cli/tests/store-runtime.test.ts @@ -0,0 +1,64 @@ +import { mkdtempSync, readdirSync, realpathSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { afterEach, expect, test } from 'vitest'; +import type { ArchitectureGraph } from '../src/graph.js'; +import { prepareStore } from '../src/store-runtime.js'; + +const graph: ArchitectureGraph = { + version: 1, + nodes: [], + edges: [], + diagnostics: [], + inspectedEntries: 0, +}; +const cleanups: (() => void)[] = []; +afterEach(() => { + while (cleanups.length) cleanups.pop()!(); +}); +const temp = (prefix: string) => { + const path = realpathSync(mkdtempSync(join(tmpdir(), prefix))); + cleanups.push(() => rmSync(path, { recursive: true, force: true })); + return path; +}; + +test('a data directory inside the analyzed root disables the store without writing there', async () => { + const root = temp('archwise-root-'); + const runtime = await prepareStore({ + enabled: true, + dataDir: join(root, '.archwise-data'), + rootPath: root, + rootLabel: 'root', + graph, + }); + expect(runtime.kind).toBe('disabled'); + expect(runtime.notices.join(' ')).toMatch(/inside the analyzed project/); + expect(readdirSync(root)).toEqual([]); +}); + +test('the analyzed root itself is also refused as a data directory', async () => { + const root = temp('archwise-root-'); + const runtime = await prepareStore({ + enabled: true, + dataDir: root, + rootPath: root, + rootLabel: 'r', + graph, + }); + expect(runtime.kind).toBe('disabled'); + expect(readdirSync(root)).toEqual([]); +}); + +test('a data directory outside the root opens the store', async () => { + const root = temp('archwise-root-'); + const data = temp('archwise-data-'); + const runtime = await prepareStore({ + enabled: true, + dataDir: data, + rootPath: root, + rootLabel: 'r', + graph, + }); + expect(runtime.kind).toBe('ready'); + if (runtime.kind === 'ready') runtime.store.close(); +}); diff --git a/docs/alpha-testing.md b/docs/alpha-testing.md index 7dd0f0c..c3ff772 100644 --- a/docs/alpha-testing.md +++ b/docs/alpha-testing.md @@ -51,7 +51,7 @@ Use `--json` for the inventory instead of the graph, or `--serve --no-open` to a ## Current limits and safety - Discovery currently covers Node package manifests and explicitly declared dependencies between uniquely identified local packages. It does **not** infer a live runtime system, traffic flows, databases or deployed infrastructure. -- Sandbox topology, simulation inputs and saved A/B snapshots are automatically persisted in browser localStorage, scoped to a deterministic discovered-graph signature. The offline Coach question index is not persisted. See [Sandbox persistence](sandbox-persistence.md) and [Scenario comparison](scenario-comparison.md). +- The Studio still persists Sandbox topology, simulation inputs and saved A/B snapshots in browser localStorage, scoped to a deterministic discovered-graph signature. The CLI already records discovered revisions in the local store outside the project (`--sessions`, `--no-store`; see [Sessions](sessions.md)), and the Studio will switch to that store in the next increment. The offline Coach question index is not persisted. See [Sandbox persistence](sandbox-persistence.md) and [Scenario comparison](scenario-comparison.md). - A deterministic Sandbox simulation is available, but it **does not measure production traffic**. It assumes a single entry node, evenly split routing across proposed links, a DAG topology, no retries and modeled capacity drops. See [Simulation assumptions](simulation.md). - There is no npm-published `npx archwise` package yet; use the compiled CLI. - The current build includes ELK and Svelte Flow and is not yet bundle-size optimized. diff --git a/docs/architecture.md b/docs/architecture.md index 07256c0..00ad18b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -37,7 +37,15 @@ The domain defines versioned graph, evidence, scenario, diagnostic, and coaching ### Local persistence -SQLite is the proposed local index for workspaces, scan metadata, graph revisions, scenarios, and sessions. Content-addressed blobs may hold larger derived artifacts. Storage lives under an OS-appropriate application data directory, not inside analyzed repositories. Schema migrations are transactional and backup before destructive changes. +SQLite is the local index ([ADR 0006](decisions/0006-local-store-node-sqlite.md)). `@archwise/storage` implements the application store ports on `node:sqlite`. It is implemented today for workspaces, graph revisions and Sandbox sessions; scan metadata and scenarios are future tables. Content-addressed blobs may later hold larger derived artifacts. + +Storage lives in an OS-appropriate application data directory, not inside analyzed repositories. On open the store does the following: +- runs an integrity check and quarantines a corrupt file; +- refuses a store written by a newer Archwise; +- backs up the file before migrating; +- applies migrations in one transaction. + +See [Sessions and the local store](sessions.md). ### Local API diff --git a/docs/code-organization.md b/docs/code-organization.md index b57191d..23ff5a5 100644 --- a/docs/code-organization.md +++ b/docs/code-organization.md @@ -1,8 +1,9 @@ # Code organization The tree below is the **target** layout. Today, `main` contains the following: -- **Packages:** `apps/{cli,server,web}` and `packages/{domain,schemas,application,test-fixtures}`. +- **Packages:** `apps/{cli,server,web}` and `packages/{domain,schemas,application,storage,test-fixtures}`. - **Graph contracts:** `archwise.graph` v1 lives in `domain` and `schemas`. +- **Sessions:** store ports and `SessionService` live in `application`; the SQLite adapter lives in `storage`. - **Alpha logic placed in apps:** manifest discovery and the loopback server are in `apps/cli`; the simulator, Sandbox persistence and coach are in `apps/web`. [ADR 0005](decisions/0005-svelte-flow-browser-workspace.md) records the Alpha logic in apps as debt, to be moved into the target packages as the matching roadmap phases land. diff --git a/docs/decisions/0006-local-store-node-sqlite.md b/docs/decisions/0006-local-store-node-sqlite.md new file mode 100644 index 0000000..145c488 --- /dev/null +++ b/docs/decisions/0006-local-store-node-sqlite.md @@ -0,0 +1,38 @@ +# ADR 0006: Local store on built-in `node:sqlite` + +- Status: Accepted +- Date: 2026-11-16 + +## Context + +Archwise must persist discovered graph revisions and Sandbox sessions so a user can start each launch fresh and later resume an earlier session (see the [sessions spec](../superpowers/specs/2026-11-16-sessions-and-local-store-design.md)). The architecture already named SQLite as the local index, stored outside analyzed repositories, with transactional, backed-up migrations. A driver had not been selected. + +## Decision + +- **Driver.** Use Node's built-in `node:sqlite` (`DatabaseSync`, plus the async `backup()`) in a new `@archwise/storage` package that implements the application store ports. On Node 24 and 26 it needs no flag and prints no warning (verified on 24.22 and 26.4). +- **Location.** Keep one database file, `archwise.db`, in the OS application-data directory: + - macOS: `~/Library/Application Support/Archwise` + - Linux: `$XDG_DATA_HOME/archwise` or `~/.local/share/archwise` + - Windows: `%LOCALAPPDATA%\Archwise` + - `ARCHWISE_DATA_DIR` overrides the default. The directory is created with mode `0700` on POSIX. +- **Concurrency.** Use WAL with a 5-second busy timeout, so two Archwise processes can share the file. +- **Integrity.** Check integrity on open. A corrupt file is quarantined (renamed, never deleted). +- **Migrations.** Before migrating, take a backup and keep the newest three. Migrations run in one transaction. A store written by a newer Archwise is refused unchanged. +- **Data placement.** + - Revisions are stored as canonical `archwise.graph` JSON. + - The Studio's view graph is stored next to each revision. + - Sessions store `archwise-sandbox` v1 text. + - Absolute workspace root paths exist only in this local file. They are never returned by the API or exported. + +## Consequences + +- **No new npm dependency and no native build step.** Packaging stays simple on all three operating systems. +- **The store is synchronous.** That suits its use: small rows on a single-user loopback server. A long scan must not hold write transactions. +- **Schema changes are append-only migrations,** each covered by tests for backup, rollback and refusal. +- **The store holds paths and Sandbox content.** `docs/security.md` documents its location and permissions, and users can delete the directory to remove all Archwise data. + +## Rejected alternatives + +- **`better-sqlite3`:** mature and fast, but a native addon. It needs prebuilt binaries per platform and Node ABI, and it adds a dependency with install scripts. The project installs with `--ignore-scripts`. +- **JSON files per session:** simple, but no atomic multi-record updates, no safe concurrent writers, and hand-rolled migrations. +- **Browser IndexedDB or localStorage:** the Studio binds a random loopback port on every launch, which changes the browser origin and so makes earlier storage unreachable. It also cannot be listed from the CLI. diff --git a/docs/implementation-roadmap.md b/docs/implementation-roadmap.md index bba29d2..500a7b3 100644 --- a/docs/implementation-roadmap.md +++ b/docs/implementation-roadmap.md @@ -40,7 +40,7 @@ Snapshot as of 2026-11-15, after PRs #5, #6 and #7 merged into `main`. Issues an |---|---|---| | 0 | Complete (2026-11-15) | — | | 1 | Complete (2026-11-15) | — | -| 2 | Partial: graph contracts slice | SQLite storage, application ports, migrations, backup/recovery, export redaction of home paths | +| 2 | Partial: graph contracts; SQLite store with ports, migrations, backup and recovery; sessions API | Studio session UI (next PR), export redaction of home paths, storage recovery documented for end users in a release guide | | 3 | Alpha only: manifest-only inventory in `apps/cli` | Budgets, ignore rules, symlink and nested-repository handling, `--repo` / `--workspace`, persisted scan metadata | | 4 | Alpha only: Node package manifests | Analyzer SDK, TS imports, HTTP/DB/queue detectors, Compose, golden graphs | | 5 | Alpha only: protected loopback server and Svelte Flow Studio | SSE progress, evidence navigation from domain revisions, accessibility, large-graph strategy | @@ -139,7 +139,13 @@ Detailed execution plan: [`superpowers/plans/2026-11-08-archwise-foundation.md`] ## Phase 2 — Domain contracts and local persistence -Status: in progress. The graph-contracts slice is implemented in `@archwise/domain` and `@archwise/schemas`. It covers the validated, immutable and canonically serialized `archwise.graph` v1 revision, strict import, and sandbox base references; see the [spec](superpowers/specs/2026-11-11-graph-contracts-design.md). SQLite persistence, application ports, migrations, backup/recovery and redaction of absolute home paths in exports remain open. The phase exit gate is not yet satisfied. +Status: in progress. The graph-contracts slice is implemented in `@archwise/domain` and `@archwise/schemas`. It covers the validated, immutable and canonically serialized `archwise.graph` v1 revision, strict import, and sandbox base references; see the [spec](superpowers/specs/2026-11-11-graph-contracts-design.md). The sessions slice adds the following (see [Sessions](sessions.md) and [ADR 0006](decisions/0006-local-store-node-sqlite.md)): +- application store ports and a `SessionService`; +- the `@archwise/storage` SQLite adapter, with transactional migrations, pre-migration backup, corruption quarantine and refusal of newer schemas; +- revision recording from discovery; +- the protected session API and `--sessions` / `--no-store`. + +Still open: the Studio session UI (the second PR of that slice) and redaction of absolute home paths in exports. The phase exit gate is not yet satisfied. ### Goal diff --git a/docs/security.md b/docs/security.md index ad078ac..72d14e9 100644 --- a/docs/security.md +++ b/docs/security.md @@ -15,6 +15,15 @@ Archwise analyzes untrusted repositories that may contain malicious files, overs - Redact common credential patterns and sensitive filenames before persistence, logs, exports, or provider context. - Disable telemetry by default. If introduced, make it opt-in, documented, inspectable, and free of file paths or graph content. +## Local store + +The local SQLite store ([ADR 0006](decisions/0006-local-store-node-sqlite.md)) lives in the user's application-data directory, which is created with mode `0700` on POSIX. It holds: +- absolute workspace root paths; +- discovered package names and manifest-relative paths; +- Sandbox documents. + +It never contains source file contents. It is not synchronized or exported, and the API never returns root paths. Session routes require the local session capability. Mutations also require a same-origin `Origin` header, a JSON content type and a body under 300,000 bytes. Users can delete the directory to remove all stored data. + ## Secret handling Archwise inventories the existence of sensitive configuration only when useful; it does not read `.env` values, private keys, credential directories, or known secret files by default. Provider keys live in the OS credential store where supported. Diagnostic bundles require preview and explicit export, with a second redaction pass. diff --git a/docs/sessions.md b/docs/sessions.md new file mode 100644 index 0000000..e689a48 --- /dev/null +++ b/docs/sessions.md @@ -0,0 +1,77 @@ +# Sessions and the local store + +Each time you launch the Studio on a project, Archwise starts a **fresh session**: the graph discovered now, plus an empty Sandbox. Sessions are saved in a local store outside your project, so earlier work can be listed and resumed, much like `/resume` in a chat tool. + +> **Status:** the store, the session API and `--sessions` are implemented. The Studio does not use them yet: it still keeps the Sandbox in browser `localStorage` (see [Sandbox persistence](sandbox-persistence.md)). Autosave, the session list in the Studio, `--resume`, and the changed-architecture notice come in the next increment. + +## What is stored, and where + +| Platform | Directory | +| -------- | ------------------------------------------------------- | +| macOS | `~/Library/Application Support/Archwise` | +| Linux | `$XDG_DATA_HOME/archwise`, or `~/.local/share/archwise` | +| Windows | `%LOCALAPPDATA%\Archwise` | + +Set `ARCHWISE_DATA_DIR` to use another directory. The store is a single SQLite file, `archwise.db`, which holds the following: + +- **Workspaces:** the absolute project root path that identifies each project. +- **Graph revisions:** the discovered package graph as an `archwise.graph` v1 revision, plus the Studio's view of it. An unchanged rescan reuses the previous revision instead of adding a new one. A rescan counts as changed when either the graph or its view differs, for example a new framework label. +- **Sessions:** the Sandbox document, a label, and creation and update times. Each session records the revision it started from. + +Archwise never writes inside the analyzed project. The API never returns the absolute root path. To remove all saved data, delete the directory. + +## Commands + +```bash +node apps/cli/dist/bin.js --sessions --path /absolute/path/to/project # list saved sessions, newest first +node apps/cli/dist/bin.js --serve --path /absolute/path/to/project # Studio with the store enabled +node apps/cli/dist/bin.js --serve --no-store --path /absolute/path/to/project # run without saving anything +``` + +Each line of `--sessions` shows, in order: + +- when the session last changed; +- its label (by default `Sandbox · N components`); +- its component count; +- `A/B` if it has saved scenario snapshots; +- `changed` if the project's discovered architecture changed since the session started; +- the session ID. + +Listing runs a discovery to compute the `changed` flag, so a changed project records a new revision. + +A session is saved only after its first Sandbox change. Launches where nothing changed leave no entry. + +## Session API (loopback, capability-protected) + +The Studio will use these endpoints. All of them require the local session cookie. Mutations (`PUT`, `PATCH`, `POST`, `DELETE`) also require a same-origin `Origin` header. `PUT` and `PATCH` also require a JSON body. + +| Method and path | Purpose | +| ----------------------------------- | --------------------------------------------------------------------------------- | +| `GET /api/v1/sessions/current` | The current session ID, whether it is persisted, and whether the store is enabled | +| `GET /api/v1/sessions` | Session summaries for this project | +| `GET /api/v1/sessions/{id}` | Sandbox document, base revision view, and whether that revision is still current | +| `POST /api/v1/sessions/{id}/resume` | Continue that session in place (later saves update it) | +| `PUT /api/v1/sessions/{id}/sandbox` | Save the Sandbox; the first save persists a fresh session | +| `PATCH /api/v1/sessions/{id}` | Rename (`{"label": "..."}`) | +| `DELETE /api/v1/sessions/{id}` | Delete a session | + +Error responses: + +- Unknown or malformed IDs return `404`, and the response never repeats the ID. +- Oversized documents return `413` (the limit is 256 KiB of Sandbox JSON). +- Invalid Sandbox documents and labels return `422`. + +## Recovery and failures + +| Situation | What Archwise does | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| Corrupt store file | It renames the file and its `-wal`/`-shm` companions to `archwise.db.corrupt-`, starts a fresh store, and prints where the old file is. | +| Upgrade to a new store schema | It backs up to `archwise.db.backup-v-` first and keeps the three newest backups (by schema version, then time). | +| Store written by a newer Archwise | It exits with code 2 and leaves the file untouched. Upgrade Archwise, or use `--no-store`. | +| Failed upgrade | It rolls back and exits with code 2. The file is unchanged and the backup is kept. | +| Data directory or store file not writable | It exits with code 2. Fix the permissions or set `ARCHWISE_DATA_DIR`. | +| Data directory inside the analyzed project | It disables the store for that run and prints a notice. Nothing is written in the project. | + +Two Archwise processes can use the store at the same time, including on first use, when both may try to create or upgrade it. Each waits up to 5 seconds for the other's lock. When both save the same session, the last write wins. + +See [ADR 0006](decisions/0006-local-store-node-sqlite.md) for the design decision. diff --git a/docs/superpowers/plans/2026-11-16-session-store.md b/docs/superpowers/plans/2026-11-16-session-store.md new file mode 100644 index 0000000..2f47d0f --- /dev/null +++ b/docs/superpowers/plans/2026-11-16-session-store.md @@ -0,0 +1,372 @@ +# Session Store (Phase 2, slice 2 — PR 1 of 2) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Persist discovered graph revisions and Sandbox sessions in a local SQLite store, behind application ports. Expose them through the protected loopback API and `archwise --sessions`. The Studio UI is PR 2. + +**Architecture:** +- `@archwise/application` gains: + - ports: `WorkspaceRepository`, `RevisionRepository`, `SessionRepository`, `Clock`, `IdGenerator`, `Digest`; + - use cases, collected in a `SessionService`; + - an in-memory adapter; + - a reusable contract suite exported from `@archwise/application/testing`. +- A new `@archwise/storage` package implements the ports with `node:sqlite`. It owns migrations, backup, quarantine and data-directory resolution. +- `apps/cli` provides three pieces: + - a revision adapter that builds an `archwise.graph` revision from the existing inventory and graph; + - the composition in `bin.ts`; + - new `/api/v1/sessions*` routes in `local-server.ts`. + +**Tech Stack:** TypeScript strict ESM, `node:sqlite` (`DatabaseSync`, `backup`), `node:crypto` (in adapters only), Vitest 5. No new npm dependencies. + +**Spec:** `docs/superpowers/specs/2026-11-16-sessions-and-local-store-design.md` (approved 2026-11-16). Builds on `docs/superpowers/specs/2026-11-11-graph-contracts-design.md`. + +## Global Constraints + +- **Package boundaries:** `application` imports only `@archwise/domain` and `@archwise/schemas`. `storage` imports `application`, `domain`, `schemas` and `node:*`. Neither `domain` nor `application` imports `node:*`. +- **Data location:** + - macOS: `~/Library/Application Support/Archwise` + - Linux: `$XDG_DATA_HOME/archwise`, else `~/.local/share/archwise` + - Windows: `%LOCALAPPDATA%\Archwise` + - `ARCHWISE_DATA_DIR` overrides all of these. + - The directory has mode `0700` on POSIX, and the file is `archwise.db`. + - Nothing is ever written inside the analyzed root. +- **IDs:** opaque, with prefixes `ws-`, `rev-` and `ses-` followed by 24 lowercase hex characters (random). They must be domain-valid IDs. +- **Sandbox documents:** + - stored as JSON text, at most 262,144 bytes in UTF-8; + - the server checks only that the text is a JSON object with `format: "archwise-sandbox"` and `version: 1`, and that it is within the size limit; + - `nodes` must be an array, used for the component count; + - snapshots are detected from `draft.savedA` / `draft.savedB` being non-null. +- **Revision fingerprint:** SHA-256 hex of `serializeGraphRevision` output for a copy whose `id`, `createdAt` and `parentRevisionId` are replaced by fixed placeholders (`rev-fingerprint`, `1970-01-01T00:00:00.000Z`, `null`). +- **API:** + - Every new route sits under `/api/v1/sessions` behind the existing capability check. + - Mutating methods (`PUT`, `PATCH`, `DELETE`) also require an `Origin` header equal to the server origin, plus `Content-Type: application/json` for bodies. + - Bodies are limited to 300,000 bytes. + - Responses never contain absolute paths or echo rejected input. + - Unknown IDs return `404 {"error":"Not found"}`. +- **Store failures:** + - **Corrupt file** (integrity check fails or open throws a SQLite corruption error): rename it to `archwise.db.corrupt-` and create a fresh store. + - **Newer schema, failed migration, or unwritable directory:** throw a `StoreUnavailableError` with a `reason` of `newer-schema`, `migration-failed` or `unwritable`. The CLI exits with code 2 and leaves the file untouched. + - `--no-store` skips the store entirely. +- **Commits:** signed off (`git commit -s`), each ending with the Co-Authored-By attribution line. Run pnpm as `npx --yes pnpm@10.34.9`. + +## Review Focus + +1. **The analyzed directory must stay byte-identical.** Running `--serve` with the store enabled, against a fixture directory, must not create `archwise.db` or any other file inside that directory (owner: Task 5 integration test). +2. **A resumed session's revision must be the one it started from.** Saving a resumed session must never change its `baseRevisionId`, even after a newer discovery revision exists (owner: Task 1 contract suite). +3. **Two processes on one database file.** Interleaved saves through two `openStore` handles on the same file must both succeed (thanks to the busy timeout) without `SQLITE_BUSY` surfacing (owner: Task 2). +4. **Sandbox text that is valid JSON but hostile.** A body like `{"format":"archwise-sandbox","version":1,"nodes":{}}`, or one with a `__proto__` key, must be rejected with `invalid-sandbox` and must not throw (owner: Task 1). +5. **A path-like session ID in the URL.** `/api/v1/sessions/..%2F..%2Fetc` and IDs longer than 128 characters must return 404 without echoing the ID (owner: Task 4). + +--- + +### Task 1: Application ports, `SessionService`, in-memory adapter and contract suite + +**Files:** +- Create: + - `packages/application/src/ports.ts` + - `packages/application/src/sandbox-text.ts` + - `packages/application/src/session-service.ts` + - `packages/application/src/memory-store.ts` + - `packages/application/src/testing/store-contract.ts` + - `packages/application/src/testing/index.ts` +- Modify: + - `packages/application/src/index.ts`, to re-export the new modules (keep `createApplicationInfo`); + - `packages/application/package.json`, adding `"./testing"` to `exports` (built `dist/testing/index.js`) and `"@archwise/schemas": "workspace:*"`. +- Test: + - `packages/application/tests/sandbox-text.test.ts` + - `packages/application/tests/session-service.test.ts` + - `packages/application/tests/memory-store.contract.test.ts` + +**Interfaces — Produces:** + +```ts +// ports.ts +export interface Workspace { readonly id: string; readonly rootPath: string; readonly createdAt: string } +export interface StoredRevision { readonly id: string; readonly workspaceId: string; readonly fingerprint: string; + readonly createdAt: string; readonly revision: GraphRevision; readonly view: string /* ArchitectureGraph JSON */ } +export interface StoredSession { readonly id: string; readonly workspaceId: string; readonly baseRevisionId: string; + readonly createdAt: string; readonly updatedAt: string; readonly label: string; readonly sandbox: string } +export interface WorkspaceRepository { resolve(rootPath: string, id: string, createdAt: string): Workspace } // returns existing row for rootPath, or inserts with given id +export interface RevisionRepository { + latest(workspaceId: string): StoredRevision | null; + get(workspaceId: string, id: string): StoredRevision | null; + insert(revision: StoredRevision): void; +} +export interface SessionRepository { + get(workspaceId: string, id: string): StoredSession | null; + list(workspaceId: string): readonly StoredSession[]; // updatedAt desc, then id asc + insert(session: StoredSession): void; + update(workspaceId: string, id: string, changes: { readonly sandbox?: string; readonly label?: string; readonly updatedAt: string }): boolean; + delete(workspaceId: string, id: string): boolean; +} +export interface Store { readonly workspaces: WorkspaceRepository; readonly revisions: RevisionRepository; readonly sessions: SessionRepository } +export interface Clock { now(): string } // domain timestamp format +export interface IdGenerator { next(prefix: 'ws' | 'rev' | 'ses'): string } +export interface Digest { sha256Hex(text: string): string } + +// sandbox-text.ts +export const MAX_SANDBOX_BYTES = 262_144; +export interface SandboxSummary { readonly componentCount: number; readonly hasSnapshots: boolean } +export function inspectSandboxText(text: string): { ok: true; summary: SandboxSummary } | { ok: false; code: 'too-large' | 'invalid-sandbox' }; + +// session-service.ts +export interface SessionSummary { readonly id: string; readonly label: string; readonly createdAt: string; readonly updatedAt: string; + readonly componentCount: number; readonly hasSnapshots: boolean; readonly baseIsCurrent: boolean } +export interface SessionDetail extends SessionSummary { readonly sandbox: string; readonly view: string } +export type ServiceError = 'not-found' | 'too-large' | 'invalid-sandbox' | 'invalid-label'; +export type ServiceResult = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly error: ServiceError }; +export interface DiscoveryInput { readonly rootPath: string; readonly view: string; + readonly build: (ids: { revisionId: string; workspaceId: string; parentRevisionId: string | null; createdAt: string }) => GraphRevision } +export class SessionService { + static open(deps: { store: Store; clock: Clock; ids: IdGenerator; digest: Digest }, discovery: DiscoveryInput): ServiceResult; // 'invalid-sandbox' never; validation failure of build() → throws RevisionInvalidError + readonly workspaceId: string; + readonly currentRevisionId: string; + current(): { readonly id: string; readonly persisted: boolean }; + list(): readonly SessionSummary[]; + get(id: string): ServiceResult; // reserved-but-unpersisted id → not-found + resume(id: string): ServiceResult; // makes it current + saveSandbox(id: string, text: string): ServiceResult; // id must be current (reserved or persisted) or a persisted id; first save of reserved id persists it + rename(id: string, label: string): ServiceResult; // label must pass domain isValidLabel and !containsSecretPattern + delete(id: string): ServiceResult; // deleting the current session reserves a fresh one +} +export class RevisionInvalidError extends Error { readonly issues: readonly ValidationIssue[] } + +// memory-store.ts +export function createMemoryStore(): Store; + +// testing/store-contract.ts — framework-agnostic: caller injects test + expect +export function defineStoreContract(name: string, factory: () => { store: Store; dispose(): void }, + t: { test: (name: string, fn: () => void) => void; expect: (v: unknown) => any }): void; +``` + +`SessionService.open` steps: +1. `workspaces.resolve(rootPath, ids.next('ws'), clock.now())`. +2. `latest = revisions.latest(ws)`. +3. `revision = createRevision(build({revisionId: ids.next('rev'), workspaceId, parentRevisionId: latest?.id ?? null, createdAt: clock.now()}))`. If this fails, throw `RevisionInvalidError`. +4. Compute the fingerprint as described in Global Constraints. +5. If it equals `latest.fingerprint`, reuse `latest` (do not insert). Otherwise insert a new revision with `view`. +6. Reserve `ids.next('ses')` as current, not persisted. + +The default label on first persist is `` `Sandbox · ${n} component${n === 1 ? '' : 's'}` ``. `baseIsCurrent` is `session.baseRevisionId === currentRevisionId`. A session's `view` is its base revision's `view`. + +- [ ] **Step 1: Write failing tests.** + - `sandbox-text.test.ts`: + - A minimal valid doc `{"format":"archwise-sandbox","version":1,"nodes":[{}],"draft":{"savedA":null,"savedB":{}}}` gives `{componentCount:1, hasSnapshots:true}`. + - Each of these gives `invalid-sandbox` (and never throws): non-JSON; a JSON array; the wrong `format`; `version: 2`; `nodes: {}`; a missing or non-object `draft`. + - **Review Focus 4:** `{"__proto__":{}}` gives `invalid-sandbox`. + - 262,145 bytes of padding gives `too-large`. + - `memory-store.contract.test.ts`: `defineStoreContract('memory', () => ({ store: createMemoryStore(), dispose() {} }), { test, expect })`. + - The contract suite in `store-contract.ts` covers: + - `resolve` is idempotent per `rootPath`, and two different roots give different workspaces. + - Revision `insert`/`get`/`latest` round-trip, and `get` with another workspace's ID returns `null`. + - Session `insert`/`get`/`list` ordering, `update` returning `false` for unknown IDs, `delete`, and workspace isolation. + - `session-service.test.ts` uses a fake clock with incrementing ISO seconds, sequential IDs (`ses-000…001`) and `digest` = identity: + - Two `open`s with an unchanged `build` produce one revision row. + - A changed `build` produces a second revision whose parent is the first. + - With no `saveSandbox`, `list()` is empty. + - The first `saveSandbox(current().id, doc)` persists the session with label `Sandbox · 1 component`. + - `get` of the reserved ID before saving gives `not-found`. + - **Review Focus 2:** resuming an old session after a newer revision gives `baseIsCurrent: false`, and a later `saveSandbox` keeps its `baseRevisionId`. + - `rename` to `''` gives `invalid-label`. + - `delete(current)` reserves a new current ID. + - An unknown ID gives `not-found` for `get`, `resume`, `rename` and `delete`. + - A `build` that produces an invalid revision makes `open` throw `RevisionInvalidError`. +- [ ] **Step 2:** Run `npx --yes pnpm@10.34.9 install --ignore-scripts && npx --yes pnpm@10.34.9 build && npx --yes pnpm@10.34.9 --filter @archwise/application test`. Expected: FAIL (modules missing). +- [ ] **Step 3:** Implement the files above. The memory store keeps `Map`s and returns frozen copies. +- [ ] **Step 4:** Run the same command. Expected: PASS. Then run `npx --yes pnpm@10.34.9 lint && npx --yes pnpm@10.34.9 boundaries`. Expected: clean. +- [ ] **Step 5:** Commit with `feat(application): session service, store ports and contract suite`. Include `pnpm-lock.yaml`. + +### Task 2: `@archwise/storage` SQLite adapter + +**Files:** +- Create: + - `packages/storage/package.json`, named `@archwise/storage`, private, ESM. Its dependencies are `@archwise/application`, `@archwise/domain` and `@archwise/schemas`, all `workspace:*`. + - `tsconfig.json`, `tsconfig.check.json` and `vitest.config.ts`, mirroring `packages/application`. + - `README.md` + - `src/index.ts`, `src/data-dir.ts`, `src/migrations.ts` and `src/sqlite-store.ts` +- Modify: `.dependency-cruiser.mjs`. Add a rule `storage-inward-only`: from `^packages/storage/src/`, imports may target only `^packages/(storage|application|domain|schemas)/` and core Node modules. +- Test: + - `packages/storage/tests/sqlite.contract.test.ts` + - `packages/storage/tests/lifecycle.test.ts` + - `packages/storage/tests/data-dir.test.ts` + +**Interfaces — Consumes:** `Store`, the repository ports, `StoredRevision` and `StoredSession` (Task 1); `defineStoreContract` from `@archwise/application/testing`; `serializeGraphRevision` and `importGraphJson` from schemas. + +**Interfaces — Produces:** + +```ts +export function resolveDataDir(env: Readonly>, platform: NodeJS.Platform, home: string): string; +export class StoreUnavailableError extends Error { readonly reason: 'newer-schema' | 'migration-failed' | 'unwritable' } +export interface OpenedStore extends Store { readonly path: string; readonly quarantinedPath: string | null; readonly backupPath: string | null; close(): void } +export function openStore(dataDir: string, options?: { readonly now?: () => Date; readonly migrations?: readonly { version: number; sql: string }[] }): Promise; // async because node:sqlite backup() is async +export const SCHEMA_VERSION = 1; +export const MIGRATIONS: readonly { readonly version: number; readonly sql: string }[]; +``` + +Schema v1 has the following tables: +- `schema_migrations(version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)` +- `workspaces(id TEXT PRIMARY KEY, root_path TEXT NOT NULL UNIQUE, created_at TEXT NOT NULL)` +- `revisions(id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL REFERENCES workspaces(id), fingerprint TEXT NOT NULL, created_at TEXT NOT NULL, document TEXT NOT NULL, view_document TEXT NOT NULL)`, with an index on `(workspace_id, created_at)` +- `sessions(id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL REFERENCES workspaces(id), base_revision_id TEXT NOT NULL REFERENCES revisions(id), created_at TEXT NOT NULL, updated_at TEXT NOT NULL, label TEXT NOT NULL, sandbox_document TEXT NOT NULL)`, with an index on `(workspace_id, updated_at)` + +Revisions are stored as `serializeGraphRevision` text and read back through `importGraphJson`. If a stored row fails to import, `get` and `latest` return `null`. `latest` orders by `created_at DESC, id DESC`. + +`openStore` performs these steps in order: +1. `mkdirSync(dataDir, {recursive: true, mode: 0o700})`. An error here becomes `unwritable`. +2. If the file exists: + - Open it and run `PRAGMA integrity_check`. If the result is not `ok`, or the open throws `SQLITE_CORRUPT`/`SQLITE_NOTADB`, close it, rename it to the quarantine name, and continue with a fresh file. Record `quarantinedPath`. + - Read `MAX(version)` from `schema_migrations`. If the table is missing, treat the version as 0. If the version is greater than `SCHEMA_VERSION`, close and throw `newer-schema`. + - If the version is below `SCHEMA_VERSION` and the file is non-empty with version ≥ 1, run `backup(db, \`${path}.backup-v${version}-${stamp}\`)` first, keep the 3 newest backups, and record `backupPath`. +3. Set `PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000; PRAGMA foreign_keys=ON`. +4. Apply the pending migrations inside one `BEGIN IMMEDIATE … COMMIT` transaction. On any error, roll back, close, and throw `migration-failed`. + +`openStore` is async because `node:sqlite`'s `backup()` is async. + +- [ ] **Step 1: Write failing tests.** + - `sqlite.contract.test.ts` runs `defineStoreContract('sqlite', …)` against a temporary directory created with `mkdtempSync(join(tmpdir(), 'archwise-store-'))`. + - `lifecycle.test.ts` covers: + - A fresh open creates `archwise.db` with `schema_migrations` at version 1. + - Reopening does not create a backup. + - A v0 file (a hand-created database without `schema_migrations` that holds a table `legacy`) gets a backup file, and the backup still contains `legacy`. + - A database with `schema_migrations` version 99 throws `newer-schema`, and its bytes are unchanged. + - A file of 4 KiB of `0x00`/text garbage is quarantined: `quarantinedPath` exists and the new store works. + - A migration list with a failing SQL statement throws `migration-failed` and leaves the file bytes unchanged. Inject it with `openStore(dir, { migrations: [...] })`; add `migrations?` to the options for tests. + - A non-writable data directory (POSIX only; skip on win32) throws `unwritable`. + - **Review Focus 3:** two `openStore` handles on the same directory perform 50 alternating `sessions.update` calls, all of which succeed. + - `data-dir.test.ts` covers the three platforms, `XDG_DATA_HOME`, and the `ARCHWISE_DATA_DIR` override. +- [ ] **Step 2:** Run `npx --yes pnpm@10.34.9 install --ignore-scripts && npx --yes pnpm@10.34.9 build && npx --yes pnpm@10.34.9 --filter @archwise/storage test`. Expected: FAIL. +- [ ] **Step 3:** Implement the package and the boundary rule. +- [ ] **Step 4:** Run the same command, then `npx --yes pnpm@10.34.9 boundaries`. Expected: PASS. +- [ ] **Step 5:** Commit with `feat(storage): SQLite session store with migrations and recovery`. + +### Task 3: CLI revision adapter + +**Files:** +- Create: `apps/cli/src/revision.ts` +- Modify: `apps/cli/package.json`, adding the dependencies `@archwise/domain`, `@archwise/schemas`, `@archwise/application` and `@archwise/storage`, all `workspace:*`. +- Test: `apps/cli/tests/revision.test.ts` + +**Interfaces — Produces:** + +```ts +export const MANIFEST_ANALYZER = { id: 'node-manifest', version: '1.0.0' } as const; +export function buildGraphRevision(graph: ArchitectureGraph, rootLabel: string, + ids: { revisionId: string; workspaceId: string; parentRevisionId: string | null; createdAt: string }): GraphRevision; +``` + +Mapping rules: +- **Repository:** one repository, `repo-root`, labelled with `rootLabel` (the root directory's base name, trimmed to 256 code points). +- **Nodes and edges:** + - Each view node becomes a `module` node with ID `` `mod-${sha256(path).slice(0, 16)}` `` and confidence `{observed, ['manifest-declared']}`, plus evidence `` `ev-${sha256('manifest:' + path).slice(0, 16)}` `` with `ruleId: 'package-manifest'`. + - Each view edge becomes a `depends-on` edge with ID `` `dep-${sha256(edge.id).slice(0, 16)}` `` and confidence `{observed, ['dependency-declared']}`, plus evidence `` `ev-${sha256('dependency:' + path).slice(0, 16)}` `` with `ruleId: 'package-dependency'`. +- **Coverage:** `MANIFEST_ANALYZER` for `repo-root`. It is `complete` when the graph has no diagnostics, `partial` otherwise. The revision `status` matches. +- **Diagnostics:** one diagnostic per category present. `Ambiguous package name…` maps to `ambiguous-package-name`, `Unresolved dependency…` to `unresolved-dependency`, and anything else to `inventory-warning`. Each has severity `warning`, ID `diag-` and no references. + +- [ ] **Step 1: Write failing tests.** + - A three-package fixture graph with one edge and one ambiguity diagnostic gives `createRevision(...).ok === true`, status `partial`, and diagnostic codes `['ambiguous-package-name']`. + - Node IDs are stable across calls and pass `isValidId`. + - An empty graph gives a valid `complete` revision. + - **Determinism:** `serializeGraphRevision` is equal for two calls with the same IDs. +- [ ] **Step 2:** Run `npx --yes pnpm@10.34.9 install --ignore-scripts && npx --yes pnpm@10.34.9 build && npx --yes pnpm@10.34.9 --filter @archwise/cli test`. Expected: FAIL. +- [ ] **Step 3:** Implement `revision.ts`. +- [ ] **Step 4:** Run the same command. Expected: PASS. +- [ ] **Step 5:** Commit with `feat(cli): map discovered package graph to archwise.graph revisions`. Include the lockfile. + +### Task 4: Session API routes in the loopback server + +**Files:** +- Modify: `apps/cli/src/local-server.ts`. Add `sessions?: SessionService | null` to `ServerOptions`, and allow `PUT`, `PATCH` and `DELETE` only on session routes. +- Test: `apps/cli/tests/session-api.test.ts` + +**Interfaces — Consumes:** `SessionService` (Task 1). + +**Routes:** all are authorized, and none accepts query strings. + +| Method and route | Response | +|---|---| +| `GET /api/v1/sessions/current` | `{id, persisted, storeEnabled: true}`. Without a service: `{id: null, persisted: false, storeEnabled: false}`. | +| `GET /api/v1/sessions` | `{sessions: SessionSummary[]}`. Without a service: 404. | +| `GET /api/v1/sessions/{id}` | `SessionDetail`, with `view` parsed into an object and `sandbox` returned as a string. | +| `POST /api/v1/sessions/{id}/resume` | `SessionDetail` | +| `PUT /api/v1/sessions/{id}/sandbox` | Body is the raw Sandbox JSON text. Returns `SessionSummary`. | +| `PATCH /api/v1/sessions/{id}` | Body `{label}`. Returns `SessionSummary`. | +| `DELETE /api/v1/sessions/{id}` | `204` | + +Error mapping: +- **IDs:** an ID is accepted only if it matches `^ses-[0-9a-f]{24}$`. Anything else returns 404. +- **Service errors:** `not-found` → 404, `too-large` → 413, `invalid-sandbox` and `invalid-label` → 422, each with `{error: }`. +- **Bodies:** a body over 300,000 bytes → 413. A missing or foreign `Origin` on a mutating method → 403. A wrong content type → 415. + +- [ ] **Step 1: Write failing tests** using a `SessionService` over `createMemoryStore()`, reusing the bootstrap-cookie helper pattern from `local-server.test.ts`: + - Without auth, every route returns 401. + - `current` returns a reserved, unpersisted ID. + - `PUT` to that ID with a valid document returns 200 and makes the session appear in the list. + - `GET` of the session returns its sandbox. + - `PATCH` renames it, and a bad label returns 422. + - `DELETE` returns 204, and a later `GET` returns 404. + - Resuming switches `current`. + - `PUT` without `Origin` returns 403. + - `PUT` with `text/plain` returns 415. + - `PUT` with 300,001 bytes returns 413. + - **Review Focus 5:** `/api/v1/sessions/..%2F..%2Fetc` and a 200-character ID return 404, and the response body does not contain the ID. + - Without a service, `current` reports `storeEnabled: false` and the list returns 404. + - The existing `/api/v1/graph` behavior is unchanged: the existing tests still pass. +- [ ] **Step 2:** Run `npx --yes pnpm@10.34.9 build && npx --yes pnpm@10.34.9 --filter @archwise/cli test`. Expected: FAIL. +- [ ] **Step 3:** Implement the routes. Read the body with a streaming byte counter that aborts past the limit. +- [ ] **Step 4:** Run the same command. Expected: PASS. +- [ ] **Step 5:** Commit with `feat(cli): protected session API on the loopback server`. + +### Task 5: CLI composition, `--sessions`, `--no-store`, and docs + +**Files:** +- Modify: + - `apps/cli/src/index.ts`: parse `--sessions` (exclusive with `--json`, `--graph` and `--serve`) and `--no-store` (only valid with `--serve`), and update the help text. + - `apps/cli/src/bin.ts`: compose `openStore(resolveDataDir(process.env, process.platform, homedir()))`, `SessionService.open`, and the server. +- Create: `apps/cli/src/store-runtime.ts`, a small composition helper that is testable without `bin.ts`. +- Test: + - `apps/cli/tests/cli.test.ts` (extend for parsing) + - `scripts/tests/session-store-integration.test.mjs` (built CLI, `ARCHWISE_DATA_DIR` set to a temporary directory) +- Docs: + - Create `docs/decisions/0006-local-store-node-sqlite.md`, covering the decision, location, alternatives (`better-sqlite3`, JSON files, IndexedDB) and consequences. + - Create `docs/sessions.md`, a user guide for the store, `--sessions`, `--no-store`, recovery behavior, data location and deleting data. It must say the Studio UI arrives in PR 2. + - Update the README documentation map; `docs/implementation-roadmap.md` (Phase 2 status and the current-state table: storage, ports and migrations are done; export redaction of home paths is still open); `docs/architecture.md` (the Local persistence section now describes what is implemented); `docs/security.md` (store contents, location and permissions); `docs/alpha-testing.md` (mention `--sessions` and `--no-store`); `docs/code-organization.md` (`storage` package now exists); the `apps/cli` and `packages/application` READMEs; and `.changeset/session-store.md`. + +**Interfaces — Produces:** + +```ts +// store-runtime.ts +export type StoreRuntime = + | { readonly kind: 'disabled' } + | { readonly kind: 'ready'; readonly service: SessionService; readonly store: OpenedStore; readonly notices: readonly string[] }; +export async function prepareStore(options: { readonly enabled: boolean; readonly dataDir: string; readonly rootPath: string; + readonly rootLabel: string; readonly graph: ArchitectureGraph }): Promise; // throws StoreUnavailableError +``` + +`--sessions` prints one line per session with the time last changed, its label, its component count, `A/B` if it has snapshots, `changed` if `baseIsCurrent` is false, and its ID. With no sessions it prints `No saved sessions for this project.` and exits 0. + +Store notices: +- After quarantine: `Store file was corrupt; moved to . Started a fresh store.` +- After a backup: `Store migrated; backup at .` + +`StoreUnavailableError` produces exit code 2 and one actionable line per reason: +- **newer-schema:** upgrade Archwise or use `--no-store`. +- **migration-failed:** the file is unchanged; report a bug; use `--no-store`. +- **unwritable:** fix the permissions of ``, or set `ARCHWISE_DATA_DIR`. + +- [ ] **Step 1: Write failing tests.** + - `cli.test.ts`: + - `--sessions` parses. + - `--sessions --serve` returns exit code 2. + - `--no-store` without `--serve` returns exit code 2. + - `--help` mentions `--sessions` and `--no-store`. + - `session-store-integration.test.mjs` uses a synthetic fixture tree and a temporary data directory: + - A first `--sessions` prints `No saved sessions`. + - A `--serve --no-open` process is started and the test bootstraps the cookie. `PUT` to the current session, then kill the process. + - A second `--sessions` lists one session. + - **Review Focus 1:** before and after, the fixture tree contains identical relative paths and bytes, and the data directory contains `archwise.db`. + - Running with `ARCHWISE_DATA_DIR` pointing at a file (so it is unwritable) makes `--serve` exit 2 with a message mentioning `ARCHWISE_DATA_DIR`. +- [ ] **Step 2:** Run `npx --yes pnpm@10.34.9 build && npx --yes pnpm@10.34.9 --filter @archwise/cli test && node --test scripts/tests/session-store-integration.test.mjs`. Expected: FAIL. +- [ ] **Step 3:** Implement the parsing, `store-runtime.ts` and the `bin.ts` wiring, then write the docs listed above. Every statement in the docs must match the delivered behavior: the session UI is PR 2. +- [ ] **Step 4:** Run `npx --yes pnpm@10.34.9 check`. Expected: everything passes. +- [ ] **Step 5:** Run a relative-link check over all `*.md` files (the same script as PR #8). Expected: all links resolve. +- [ ] **Step 6:** Commit with `feat(cli): persist sessions locally with --sessions and --no-store`, then push and open a PR against `main`, wait for all required checks, and merge. diff --git a/docs/superpowers/specs/2026-11-16-sessions-and-local-store-design.md b/docs/superpowers/specs/2026-11-16-sessions-and-local-store-design.md new file mode 100644 index 0000000..d2779e0 --- /dev/null +++ b/docs/superpowers/specs/2026-11-16-sessions-and-local-store-design.md @@ -0,0 +1,169 @@ +# Sessions and local store: second Phase 2 slice + +Status: approved by the owner on 2026-11-16. Builder-check questions are resolved below as Claude's calls. + +## Intent + +The owner's words: *start fresh, but with a way to recover previous sessions, like `/resume`*. + +Every launch of Archwise on a project opens a clean session. Everything the user does in it is saved automatically and locally. A session list lets the user resume any earlier session exactly as it was. Losing a carefully built Sandbox must never happen silently. That is the failure this slice exists to prevent. + +The slice also delivers the Phase 2 persistence work in the roadmap: application ports, a SQLite adapter, transactional migrations, backup and corruption recovery. It does so through a feature a person actually uses, instead of storage built for its own sake. + +## Goals + +1. **A fresh session on each launch.** Each `--serve` launch starts a new session based on the graph revision discovered now, with an empty Sandbox. +2. **Automatic saving.** Sandbox changes autosave to the local store. The user never has to export to keep their work. +3. **Listing and resuming sessions.** + - The Studio lists previous sessions for the same project, newest first. Each entry shows when it was last changed, its label, the number of proposed components, whether A/B snapshots exist, and whether the discovered architecture changed since the session began. + - Resuming a session restores its Sandbox and shows **the graph revision it was based on, unchanged**. When that revision differs from the current discovery, a visible notice says so. +4. **CLI parity.** `archwise --sessions` lists the sessions; `archwise --serve --resume ` opens the Studio on that session. +5. **Persisted revisions.** Discovered graphs are stored as validated `archwise.graph` v1 revisions (the contracts from slice 1). An unchanged rescan reuses the latest revision instead of duplicating it. +6. **Store lifecycle.** The store has transactional migrations, a backup before every migration, an integrity check on open with quarantine of a corrupt file, and safe concurrent access by two Archwise processes. + +## Non-goals + +- Rebasing an old Sandbox onto a newer revision. Rebase, conflicts and operation logs are Phase 7. A resumed session only shows a notice. +- A revision history browser, file watching or incremental rescans (Phase 6). +- Syncing or exporting sessions anywhere. The existing Sandbox JSON export/import stays as the portable path. +- Automatic pruning of old sessions. Users may delete a session explicitly. +- Changing the `archwise-sandbox` v1 document format. + +## Anti-goals + +These would make the slice a failure even if it works: + +- **Writing anything inside the analyzed repository.** The store lives only in the user's application-data directory. +- **A session list cluttered with empty sessions.** A session is persisted only after its first Sandbox change. Launches where the user changed nothing leave no trace. +- **A resumed session that silently shows today's graph under yesterday's Sandbox.** +- **Losing data on migration failure or a corrupt file.** Recovery keeps the old file. It never deletes it. +- **Absolute paths or store contents leaving the machine** through exports, logs or API responses. + +## Constraints + +- **`node:sqlite`** (built into Node, verified on 24.22 and 26.4 without flags or warnings). No new npm dependency. +- **Package boundaries** (AGENTS.md): + - `packages/application` defines ports and use cases and depends only on domain and schemas. + - A new `packages/storage` implements the ports with SQLite. + - `apps/cli` composes the pieces. + - `domain` stays pure. +- **Store location:** + - macOS: `~/Library/Application Support/Archwise` + - Linux: `$XDG_DATA_HOME/archwise`, else `~/.local/share/archwise` + - Windows: `%LOCALAPPDATA%\Archwise` + - `ARCHWISE_DATA_DIR` overrides the location (used by tests). + - The directory is created with mode `0700` on POSIX. +- **Workspace identity:** the canonical absolute root path, stored locally only. The browser receives opaque workspace and session IDs and never a path. +- **Loopback API rules stay unchanged:** session capability token, origin checks and request-size limits. New endpoints are versioned under `/api/v1/`. +- **Sandbox documents** are stored as the existing `archwise-sandbox` v1 JSON: + - limited to 256 KiB; + - the server checks it is JSON with the expected `format` and `version` and within the size limit; + - the web app performs full validation before applying it, as its import path does today. + +## Decisions taken in this design + +All are Claude's calls; the owner can override any of them. + +- **One database file**, `archwise.db`, holds all workspaces. It uses WAL journaling, a 5-second busy timeout and foreign keys. +- **Tables:** + - `schema_migrations(version, applied_at)` + - `workspaces(id, root_path UNIQUE, created_at)` + - `revisions(id, workspace_id, fingerprint, created_at, document, view_document)`. + - `document` is the canonical `archwise.graph` JSON: the evidence record. + - `view_document` is the Studio's existing `ArchitectureGraph` JSON produced by the same discovery run (see the next section). + - The fingerprint is a SHA-256 of the canonical JSON with `id`, `createdAt` and `parentRevisionId` removed, so an unchanged rescan matches and deduplicates. + - A new revision's parent is the workspace's latest revision. + - `sessions(id, workspace_id, base_revision_id, created_at, updated_at, label, sandbox_document)` +- **IDs** are random, prefixed and opaque (`ws-`, `rev-`, `ses-`), created behind the application `IdGenerator` port. Time comes from a `Clock` port. +- **Revisions come from the existing CLI package graph** through a new adapter: + - each package becomes a `module` node; + - each declared internal dependency becomes a `depends-on` edge; + - the evidence is the package's relative `package.json` path; + - coverage is the manifest analyzer. + This is the first real use of the slice-1 contracts. +- **What the Studio renders.** The Studio keeps rendering its existing `ArchitectureGraph` view. Each revision stores that view next to the canonical document, and a resumed session receives its base revision's stored view. This keeps several things unchanged: + - the current UI, framework labels and diagnostic text; + - the Sandbox `projectSignature`; + - compatibility with existing Sandbox JSON exports; + - the output of `/api/v1/graph` and `--graph`. + + Moving the web to render `archwise.graph` directly is Phase 5 work, tracked with the ADR 0005 debt. Revision node IDs are new domain-valid IDs derived deterministically from the package's relative manifest path. The view keeps its existing IDs. +- **Session lifecycle** (mirrors `/resume`): + - At launch the server reserves a session ID for the new session but does not persist it. The web receives it from `GET /api/v1/sessions/current`. + - The first `PUT .../sandbox` to that reserved ID creates the persisted session. Before that, `GET` and `DELETE` on the reserved ID return 404. + - Resuming continues the same session **in place**: later saves update it and bump `updated_at`, like continuing a conversation. Resume is triggered from the session list or with `--resume`. It makes that session the current one for this server, and `GET .../current` returns it. + - When two processes save the same session, the last write wins. +- **Default label**, for example `Sandbox · 3 components`. Renaming is allowed. Labels follow the domain label rules. +- **Autosave:** + - The web app debounces saves (about 750 ms) to `PUT /api/v1/sessions/{id}/sandbox`. + - The first save creates the persisted session. + - Save failures show a visible, non-blocking "not saved" indicator and are retried. The in-memory Sandbox is never discarded. +- **Browser `localStorage` is retired for Sandbox state.** It is not migrated automatically, because each launch binds a random port and therefore a new browser origin, so earlier launches' storage is unreachable. Users with old Sandboxes use the existing JSON export and import. The docs say so. +- **Migration safety:** + - Before running migrations on an existing file, `node:sqlite` `backup()` copies it to `archwise.db.backup-v-`, keeping the three newest copies. + - Migrations run in one transaction. + - A database whose schema version is newer than the running Archwise refuses to open and prints an actionable message. It is not modified. +- **Corruption recovery:** + - `PRAGMA integrity_check` runs on open. + - A failing file is renamed to `archwise.db.corrupt-`, and a fresh store is created. + - The CLI prints where the old file is. + - Archwise still starts, because the store is non-essential to inspection. +- **Other store failures exit with an actionable message (exit code 2) and change nothing.** These are a newer-schema file, a failed migration (rolled back, backup kept) and an unwritable data directory. `--no-store` explicitly runs without sessions (no autosave, no session list), and the Studio shows that state. `--sessions` follows the same rules. +- **Node runtime:** `node:sqlite` is available without flags on every Node 24 and 26 release, so `engines` stays unchanged. Early 24.x releases may print an experimental warning, which is acceptable. CI runs the latest 24 and 26. +- **Session deletion** is explicit, from the session list, with a confirmation step. + +## Interfaces the builder must honor + +- **`packages/application` ports:** + - `RevisionRepository`: `saveIfChanged(workspaceId, revision)`, `get(id)`, `latest(workspaceId)` + - `SessionRepository`: `create`, `get`, `list(workspaceId)`, `saveSandbox`, `rename`, `delete` + - `WorkspaceRepository`: `resolve(rootPath)` + - `Clock` + - `IdGenerator` +- **`packages/application` use cases:** `recordDiscovery`, `startSession`, `listSessions`, `resumeSession`, `saveSandbox`, `deleteSession`. +- **Contract tests:** one shared suite runs against an in-memory adapter (in application tests) and the SQLite adapter (in storage tests). +- **API, all behind the existing session capability:** + - `GET /api/v1/sessions/current`: the current (reserved or resumed) session ID and whether the store is enabled. + - `GET /api/v1/sessions`: list for the current workspace. + - `GET /api/v1/sessions/{id}`: session, base revision graph and the `baseIsCurrent` flag. + - `PUT /api/v1/sessions/{id}/sandbox` + - `PATCH /api/v1/sessions/{id}`: rename. + - `DELETE /api/v1/sessions/{id}` + - The existing graph endpoint keeps working. + +## Acceptance + +- Two launches with no Sandbox change leave zero persisted sessions. +- **Build, quit, relaunch, resume:** + 1. Build a Sandbox with A/B snapshots. + 2. Quit and relaunch: the Sandbox is empty. + 3. Resume: identical components, positions, parameters and snapshots. + 4. This is covered in the real-browser smoke test. +- After changing a fixture manifest, a resumed session shows its original graph and the "architecture changed" notice. A new launch shows the new graph. +- An unchanged rescan does not add a revision row. +- **Migrations:** + - A backup file exists after a migration. + - A failing migration leaves the original file unchanged. + - A newer-schema file is refused untouched. +- A corrupted file is quarantined and Archwise starts with a fresh store. +- Two processes saving concurrently do not corrupt the store. +- The analyzed fixture directory is byte-identical before and after all tests. +- API responses contain no absolute paths, and unknown session IDs return 404 without echoing input. +- `pnpm check`, the CI matrix, CodeQL and the browser smoke all pass. The docs describe the delivered behavior, including the roadmap Phase 2 status and an ADR for the storage choice and data location. + +## Left to the builder + +- Exact module split inside `packages/storage`. +- SQL statement style. +- UI placement and visual design of the session list (keep it consistent with the existing Studio). +- Debounce tuning. +- How the CLI formats the `--sessions` table. + +## Delivery + +This ships as two PRs: + +1. **Store and application:** ports, use cases, in-memory and SQLite adapters, migrations, recovery, the revision adapter, CLI `--sessions`, and API endpoints with tests. +2. **Studio:** autosave, the session list and resume, the changed-architecture notice, retiring `localStorage`, `--resume`, the `--no-store` state, and the browser smoke extension. + +Each PR updates the docs it affects. diff --git a/packages/application/README.md b/packages/application/README.md index 40cf02b..4f3c302 100644 --- a/packages/application/README.md +++ b/packages/application/README.md @@ -1,5 +1,14 @@ # @archwise/application -Application metadata composed from public domain contracts; no concrete adapters. +Use cases and ports. Depends only on `@archwise/domain` and `@archwise/schemas`; it never imports concrete adapters or Node APIs. -Public exports live in `src/index.ts`. Tests live in `tests/`. Run `pnpm --filter @archwise/application test` from the root. Build dependencies first with `pnpm build`. +- **Store ports:** `WorkspaceRepository`, `RevisionRepository` and `SessionRepository`, plus `Clock`, `IdGenerator` and `Digest`. +- **`SessionService`:** + - records a discovery run as a revision, and reuses the latest revision when the graph fingerprint is unchanged; + - reserves a fresh session per launch and persists it on its first Sandbox save; + - lists, resumes (in place), renames and deletes sessions. +- **`inspectSandboxText`:** an envelope check for `archwise-sandbox` v1 documents, limited to 256 KiB. +- **`createMemoryStore`:** an in-memory adapter. +- **`@archwise/application/testing`:** exports `defineStoreContract`, the behavioral contract that every store adapter runs (memory here; SQLite in `@archwise/storage`). + +Public exports live in `src/index.ts` and `src/testing/index.ts`. Tests live in `tests/`. Run `pnpm --filter @archwise/application test` from the root, after `pnpm build`. diff --git a/packages/application/package.json b/packages/application/package.json index 1b45ca5..ed76e28 100644 --- a/packages/application/package.json +++ b/packages/application/package.json @@ -8,6 +8,10 @@ ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" + }, + "./testing": { + "types": "./dist/testing/index.d.ts", + "import": "./dist/testing/index.js" } }, "files": [ @@ -19,6 +23,7 @@ "test": "vitest run" }, "dependencies": { - "@archwise/domain": "workspace:*" + "@archwise/domain": "workspace:*", + "@archwise/schemas": "workspace:*" } } diff --git a/packages/application/src/index.ts b/packages/application/src/index.ts index e06c969..762869b 100644 --- a/packages/application/src/index.ts +++ b/packages/application/src/index.ts @@ -1,4 +1,10 @@ import { CURRENT_SNAPSHOT_VERSION, type SnapshotVersion } from '@archwise/domain'; + export function createApplicationInfo(): Readonly<{ snapshotVersion: SnapshotVersion }> { return Object.freeze({ snapshotVersion: CURRENT_SNAPSHOT_VERSION }); } + +export * from './ports.js'; +export * from './sandbox-text.js'; +export * from './session-service.js'; +export * from './memory-store.js'; diff --git a/packages/application/src/memory-store.ts b/packages/application/src/memory-store.ts new file mode 100644 index 0000000..f4b69f3 --- /dev/null +++ b/packages/application/src/memory-store.ts @@ -0,0 +1,65 @@ +import type { SessionChanges, Store, StoredRevision, StoredSession, Workspace } from './ports.js'; + +const byUpdatedDesc = (a: StoredSession, b: StoredSession): number => + a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : a.id < b.id ? -1 : 1; + +/** In-memory adapter used by tests and by contract verification. */ +export function createMemoryStore(): Store { + const workspaces = new Map(); + const revisions = new Map(); + const sessions = new Map(); + const inWorkspace = (value: T | undefined, ws: string) => + value && value.workspaceId === ws ? value : null; + + return { + workspaces: { + resolve(rootPath, id, createdAt) { + const existing = workspaces.get(rootPath); + if (existing) return existing; + const created = Object.freeze({ id, rootPath, createdAt }); + workspaces.set(rootPath, created); + return created; + }, + }, + revisions: { + latest(workspaceId) { + let best: StoredRevision | null = null; + for (const revision of revisions.values()) { + if (revision.workspaceId !== workspaceId) continue; + if ( + !best || + revision.createdAt > best.createdAt || + (revision.createdAt === best.createdAt && revision.id > best.id) + ) { + best = revision; + } + } + return best; + }, + get: (workspaceId, id) => inWorkspace(revisions.get(id), workspaceId), + insert(revision) { + if (revisions.has(revision.id)) throw new Error('Duplicate revision'); + revisions.set(revision.id, Object.freeze({ ...revision })); + }, + }, + sessions: { + get: (workspaceId, id) => inWorkspace(sessions.get(id), workspaceId), + list: (workspaceId) => + [...sessions.values()].filter((s) => s.workspaceId === workspaceId).sort(byUpdatedDesc), + insert(session) { + if (sessions.has(session.id)) throw new Error('Duplicate session'); + sessions.set(session.id, Object.freeze({ ...session })); + }, + update(workspaceId, id, changes: SessionChanges) { + const existing = inWorkspace(sessions.get(id), workspaceId); + if (!existing) return false; + sessions.set(id, Object.freeze({ ...existing, ...changes })); + return true; + }, + delete(workspaceId, id) { + if (!inWorkspace(sessions.get(id), workspaceId)) return false; + return sessions.delete(id); + }, + }, + }; +} diff --git a/packages/application/src/ports.ts b/packages/application/src/ports.ts new file mode 100644 index 0000000..ae75ed7 --- /dev/null +++ b/packages/application/src/ports.ts @@ -0,0 +1,78 @@ +import type { GraphRevision } from '@archwise/domain'; + +/* + * Application ports. Adapters (memory, SQLite) implement them; use cases depend only on these. + * Absolute root paths live only in local storage and are never returned through the API. + */ + +export interface Workspace { + readonly id: string; + readonly rootPath: string; + readonly createdAt: string; +} + +export interface StoredRevision { + readonly id: string; + readonly workspaceId: string; + readonly fingerprint: string; + readonly createdAt: string; + readonly revision: GraphRevision; + /** The Studio's ArchitectureGraph JSON produced by the same discovery run. */ + readonly view: string; +} + +export interface StoredSession { + readonly id: string; + readonly workspaceId: string; + readonly baseRevisionId: string; + readonly createdAt: string; + readonly updatedAt: string; + readonly label: string; + /** archwise-sandbox v1 JSON text. */ + readonly sandbox: string; +} + +export interface SessionChanges { + readonly sandbox?: string; + readonly label?: string; + readonly updatedAt: string; +} + +export interface WorkspaceRepository { + /** Returns the workspace for `rootPath`, inserting it with `id` and `createdAt` when new. */ + resolve(rootPath: string, id: string, createdAt: string): Workspace; +} + +export interface RevisionRepository { + latest(workspaceId: string): StoredRevision | null; + get(workspaceId: string, id: string): StoredRevision | null; + insert(revision: StoredRevision): void; +} + +export interface SessionRepository { + get(workspaceId: string, id: string): StoredSession | null; + /** Newest `updatedAt` first, then ascending ID. */ + list(workspaceId: string): readonly StoredSession[]; + insert(session: StoredSession): void; + update(workspaceId: string, id: string, changes: SessionChanges): boolean; + delete(workspaceId: string, id: string): boolean; +} + +export interface Store { + readonly workspaces: WorkspaceRepository; + readonly revisions: RevisionRepository; + readonly sessions: SessionRepository; +} + +export interface Clock { + /** Canonical UTC millisecond timestamp (domain format). */ + now(): string; +} + +export interface IdGenerator { + next(prefix: 'ws' | 'rev' | 'ses'): string; +} + +export interface Digest { + sha256Hex(text: string): string; +} diff --git a/packages/application/src/sandbox-text.ts b/packages/application/src/sandbox-text.ts new file mode 100644 index 0000000..2445640 --- /dev/null +++ b/packages/application/src/sandbox-text.ts @@ -0,0 +1,49 @@ +/** Size limit shared with the Studio's archwise-sandbox import. */ +export const MAX_SANDBOX_BYTES = 262_144; + +export interface SandboxSummary { + readonly componentCount: number; + readonly hasSnapshots: boolean; +} + +export type SandboxInspection = + | { readonly ok: true; readonly summary: SandboxSummary } + | { readonly ok: false; readonly code: 'too-large' | 'invalid-sandbox' }; + +const isObject = (value: unknown): value is Record => + typeof value === 'object' && value !== null && !Array.isArray(value); + +/** + * Envelope check only. The Studio performs full archwise-sandbox validation before applying a + * document; the store must merely refuse oversized or non-sandbox payloads. + */ +export function inspectSandboxText(text: string): SandboxInspection { + if (new TextEncoder().encode(text).byteLength > MAX_SANDBOX_BYTES) { + return { ok: false, code: 'too-large' }; + } + let parsed: unknown; + try { + parsed = JSON.parse(text); + } catch { + return { ok: false, code: 'invalid-sandbox' }; + } + if ( + !isObject(parsed) || + parsed.format !== 'archwise-sandbox' || + parsed.version !== 1 || + !Array.isArray(parsed.nodes) || + !isObject(parsed.draft) + ) { + return { ok: false, code: 'invalid-sandbox' }; + } + const draft = parsed.draft; + return { + ok: true, + summary: { + componentCount: parsed.nodes.length, + hasSnapshots: + (draft.savedA !== null && draft.savedA !== undefined) || + (draft.savedB !== null && draft.savedB !== undefined), + }, + }; +} diff --git a/packages/application/src/session-service.ts b/packages/application/src/session-service.ts new file mode 100644 index 0000000..39cc4f9 --- /dev/null +++ b/packages/application/src/session-service.ts @@ -0,0 +1,223 @@ +import { + containsSecretPattern, + createRevision, + isValidLabel, + type GraphRevision, + type ValidationIssue, +} from '@archwise/domain'; +import { serializeGraphRevision } from '@archwise/schemas'; +import type { Clock, Digest, IdGenerator, Store, StoredRevision, StoredSession } from './ports.js'; +import { inspectSandboxText } from './sandbox-text.js'; + +export interface SessionSummary { + readonly id: string; + readonly label: string; + readonly createdAt: string; + readonly updatedAt: string; + readonly componentCount: number; + readonly hasSnapshots: boolean; + readonly baseIsCurrent: boolean; +} + +export interface SessionDetail extends SessionSummary { + readonly sandbox: string; + readonly view: string; +} + +export type ServiceError = 'not-found' | 'too-large' | 'invalid-sandbox' | 'invalid-label'; +export type ServiceResult = + { readonly ok: true; readonly value: T } | { readonly ok: false; readonly error: ServiceError }; + +export interface RevisionIds { + readonly revisionId: string; + readonly workspaceId: string; + readonly parentRevisionId: string | null; + readonly createdAt: string; +} + +export interface DiscoveryInput { + readonly rootPath: string; + readonly view: string; + /** + * The view content that must match for a revision to be reused (e.g. framework labels and + * diagnostic text the canonical revision does not carry), excluding volatile counters. + */ + readonly viewIdentity: string; + readonly build: (ids: RevisionIds) => GraphRevision; +} + +export interface SessionServiceDeps { + readonly store: Store; + readonly clock: Clock; + readonly ids: IdGenerator; + readonly digest: Digest; +} + +export class RevisionInvalidError extends Error { + readonly issues: readonly ValidationIssue[]; + constructor(issues: readonly ValidationIssue[]) { + super('Discovered graph is not a valid archwise.graph revision'); + this.name = 'RevisionInvalidError'; + this.issues = issues; + } +} + +const fail = (error: ServiceError): { readonly ok: false; readonly error: ServiceError } => ({ + ok: false, + error, +}); + +const defaultLabel = (count: number): string => + `Sandbox · ${count} component${count === 1 ? '' : 's'}`; + +/** + * Fingerprint of the discovered content: the canonical revision (independent of identity, + * time and parent) plus the view identity, so a changed view never reuses a stale stored view. + */ +function fingerprint(revision: GraphRevision, viewIdentity: string, digest: Digest): string { + const serialized = serializeGraphRevision({ + ...revision, + id: 'rev-fingerprint', + createdAt: '1970-01-01T00:00:00.000Z', + parentRevisionId: null, + }); + if (!serialized.ok) throw new RevisionInvalidError(serialized.issues); + return digest.sha256Hex(`${serialized.value}\n${viewIdentity}`); +} + +/** + * Sessions for one workspace and one discovery run. Each run reserves a fresh session that is + * persisted only on its first Sandbox save; resuming continues a stored session in place. + */ +export class SessionService { + readonly workspaceId: string; + readonly currentRevisionId: string; + readonly #deps: SessionServiceDeps; + #current: { id: string; persisted: boolean }; + + private constructor(deps: SessionServiceDeps, workspaceId: string, revisionId: string) { + this.#deps = deps; + this.workspaceId = workspaceId; + this.currentRevisionId = revisionId; + this.#current = { id: deps.ids.next('ses'), persisted: false }; + } + + static open(deps: SessionServiceDeps, discovery: DiscoveryInput): ServiceResult { + const { store, clock, ids, digest } = deps; + const workspace = store.workspaces.resolve(discovery.rootPath, ids.next('ws'), clock.now()); + const latest = store.revisions.latest(workspace.id); + const created = createRevision( + discovery.build({ + revisionId: ids.next('rev'), + workspaceId: workspace.id, + parentRevisionId: latest?.id ?? null, + createdAt: clock.now(), + }), + ); + if (!created.ok) throw new RevisionInvalidError(created.issues); + const print = fingerprint(created.value, discovery.viewIdentity, digest); + let revisionId = created.value.id; + if (latest && latest.fingerprint === print) { + revisionId = latest.id; + } else { + store.revisions.insert({ + id: created.value.id, + workspaceId: workspace.id, + fingerprint: print, + createdAt: created.value.createdAt, + revision: created.value, + view: discovery.view, + }); + } + return { ok: true, value: new SessionService(deps, workspace.id, revisionId) }; + } + + current(): { readonly id: string; readonly persisted: boolean } { + return { ...this.#current }; + } + + list(): readonly SessionSummary[] { + return this.#deps.store.sessions + .list(this.workspaceId) + .map((session) => this.#summary(session)); + } + + get(id: string): ServiceResult { + const session = this.#deps.store.sessions.get(this.workspaceId, id); + if (!session) return fail('not-found'); + const base = this.#deps.store.revisions.get(this.workspaceId, session.baseRevisionId); + if (!base) return fail('not-found'); + return { ok: true, value: this.#detail(session, base) }; + } + + resume(id: string): ServiceResult { + const detail = this.get(id); + if (detail.ok) this.#current = { id, persisted: true }; + return detail; + } + + saveSandbox(id: string, text: string): ServiceResult { + const isReserved = id === this.#current.id && !this.#current.persisted; + const existing = isReserved ? null : this.#deps.store.sessions.get(this.workspaceId, id); + if (!isReserved && !existing) return fail('not-found'); + const inspection = inspectSandboxText(text); + if (!inspection.ok) return fail(inspection.code); + const now = this.#deps.clock.now(); + if (isReserved) { + this.#deps.store.sessions.insert({ + id, + workspaceId: this.workspaceId, + baseRevisionId: this.currentRevisionId, + createdAt: now, + updatedAt: now, + label: defaultLabel(inspection.summary.componentCount), + sandbox: text, + }); + this.#current = { id, persisted: true }; + } else { + this.#deps.store.sessions.update(this.workspaceId, id, { sandbox: text, updatedAt: now }); + } + return this.#summaryById(id); + } + + rename(id: string, label: string): ServiceResult { + if (!this.#deps.store.sessions.get(this.workspaceId, id)) return fail('not-found'); + if (!isValidLabel(label) || containsSecretPattern(label)) return fail('invalid-label'); + this.#deps.store.sessions.update(this.workspaceId, id, { + label, + updatedAt: this.#deps.clock.now(), + }); + return this.#summaryById(id); + } + + delete(id: string): ServiceResult { + if (!this.#deps.store.sessions.delete(this.workspaceId, id)) return fail('not-found'); + if (id === this.#current.id) { + this.#current = { id: this.#deps.ids.next('ses'), persisted: false }; + } + return { ok: true, value: null }; + } + + #summaryById(id: string): ServiceResult { + const session = this.#deps.store.sessions.get(this.workspaceId, id); + return session ? { ok: true, value: this.#summary(session) } : fail('not-found'); + } + + #summary(session: StoredSession): SessionSummary { + const inspection = inspectSandboxText(session.sandbox); + const summary = inspection.ok ? inspection.summary : { componentCount: 0, hasSnapshots: false }; + return { + id: session.id, + label: session.label, + createdAt: session.createdAt, + updatedAt: session.updatedAt, + componentCount: summary.componentCount, + hasSnapshots: summary.hasSnapshots, + baseIsCurrent: session.baseRevisionId === this.currentRevisionId, + }; + } + + #detail(session: StoredSession, base: StoredRevision): SessionDetail { + return { ...this.#summary(session), sandbox: session.sandbox, view: base.view }; + } +} diff --git a/packages/application/src/testing/index.ts b/packages/application/src/testing/index.ts new file mode 100644 index 0000000..a550c28 --- /dev/null +++ b/packages/application/src/testing/index.ts @@ -0,0 +1 @@ +export * from './store-contract.js'; diff --git a/packages/application/src/testing/store-contract.ts b/packages/application/src/testing/store-contract.ts new file mode 100644 index 0000000..84749dd --- /dev/null +++ b/packages/application/src/testing/store-contract.ts @@ -0,0 +1,126 @@ +import type { GraphRevision } from '@archwise/domain'; +import type { Store, StoredRevision, StoredSession } from '../ports.js'; + +/** Minimal injected test API so the contract does not depend on a test framework. */ +export interface ContractHarness { + readonly test: (name: string, fn: () => void | Promise) => void; + readonly expect: (value: unknown) => { + toBe(expected: unknown): void; + toEqual(expected: unknown): void; + toBeNull(): void; + not: { toBe(expected: unknown): void }; + }; +} + +const revisionFor = (id: string, workspaceId: string, createdAt: string): GraphRevision => ({ + id, + workspaceId, + parentRevisionId: null, + createdAt, + status: 'partial', + repositories: [], + coverage: [], + evidence: [], + nodes: [], + edges: [], + diagnostics: [], +}); + +const storedRevision = (id: string, workspaceId: string, createdAt: string): StoredRevision => ({ + id, + workspaceId, + fingerprint: `fp-${id}`, + createdAt, + revision: revisionFor(id, workspaceId, createdAt), + view: '{"version":1}', +}); + +const session = ( + id: string, + workspaceId: string, + baseRevisionId: string, + updatedAt: string, +): StoredSession => ({ + id, + workspaceId, + baseRevisionId, + createdAt: '2026-11-16T00:00:00.000Z', + updatedAt, + label: `Label ${id}`, + sandbox: '{"format":"archwise-sandbox","version":1,"nodes":[],"draft":{}}', +}); + +/** Behavioral contract every Store adapter must satisfy. */ +export function defineStoreContract( + name: string, + factory: () => { store: Store; dispose(): void } | Promise<{ store: Store; dispose(): void }>, + t: ContractHarness, +): void { + const run = (title: string, body: (store: Store) => void) => + t.test(`${name} store: ${title}`, async () => { + const handle = await factory(); + try { + body(handle.store); + } finally { + handle.dispose(); + } + }); + + run('resolves one workspace per root path', (store) => { + const a = store.workspaces.resolve('/root/a', 'ws-a', '2026-11-16T00:00:00.000Z'); + const again = store.workspaces.resolve('/root/a', 'ws-other', '2026-11-17T00:00:00.000Z'); + const b = store.workspaces.resolve('/root/b', 'ws-b', '2026-11-16T00:00:00.000Z'); + t.expect(again).toEqual(a); + t.expect(a.id).toBe('ws-a'); + t.expect(b.id).not.toBe(a.id); + }); + + run('round-trips revisions and returns the latest per workspace', (store) => { + store.workspaces.resolve('/root/a', 'ws-a', '2026-11-16T00:00:00.000Z'); + store.workspaces.resolve('/root/b', 'ws-b', '2026-11-16T00:00:00.000Z'); + t.expect(store.revisions.latest('ws-a')).toBeNull(); + const first = storedRevision('rev-1', 'ws-a', '2026-11-16T00:00:01.000Z'); + const second = storedRevision('rev-2', 'ws-a', '2026-11-16T00:00:02.000Z'); + store.revisions.insert(first); + store.revisions.insert(second); + store.revisions.insert(storedRevision('rev-3', 'ws-b', '2026-11-16T00:00:03.000Z')); + t.expect(store.revisions.get('ws-a', 'rev-1')).toEqual(first); + t.expect(store.revisions.latest('ws-a')).toEqual(second); + t.expect(store.revisions.get('ws-b', 'rev-1')).toBeNull(); + }); + + run('lists sessions newest first and isolates workspaces', (store) => { + store.workspaces.resolve('/root/a', 'ws-a', '2026-11-16T00:00:00.000Z'); + store.workspaces.resolve('/root/b', 'ws-b', '2026-11-16T00:00:00.000Z'); + store.revisions.insert(storedRevision('rev-1', 'ws-a', '2026-11-16T00:00:01.000Z')); + store.revisions.insert(storedRevision('rev-2', 'ws-b', '2026-11-16T00:00:01.000Z')); + store.sessions.insert(session('ses-old', 'ws-a', 'rev-1', '2026-11-16T00:00:05.000Z')); + store.sessions.insert(session('ses-new', 'ws-a', 'rev-1', '2026-11-16T00:00:09.000Z')); + store.sessions.insert(session('ses-b', 'ws-b', 'rev-2', '2026-11-16T00:00:07.000Z')); + t.expect(store.sessions.list('ws-a').map((s) => s.id)).toEqual(['ses-new', 'ses-old']); + t.expect(store.sessions.get('ws-b', 'ses-new')).toBeNull(); + }); + + run('updates, refuses unknown ids and deletes sessions', (store) => { + store.workspaces.resolve('/root/a', 'ws-a', '2026-11-16T00:00:00.000Z'); + store.revisions.insert(storedRevision('rev-1', 'ws-a', '2026-11-16T00:00:01.000Z')); + store.sessions.insert(session('ses-1', 'ws-a', 'rev-1', '2026-11-16T00:00:05.000Z')); + const changed = store.sessions.update('ws-a', 'ses-1', { + label: 'Renamed', + sandbox: '{"x":1}', + updatedAt: '2026-11-16T00:00:06.000Z', + }); + t.expect(changed).toBe(true); + t.expect(store.sessions.get('ws-a', 'ses-1')).toEqual({ + ...session('ses-1', 'ws-a', 'rev-1', '2026-11-16T00:00:06.000Z'), + label: 'Renamed', + sandbox: '{"x":1}', + }); + t.expect( + store.sessions.update('ws-a', 'ses-missing', { updatedAt: '2026-11-16T00:00:07.000Z' }), + ).toBe(false); + t.expect(store.sessions.delete('ws-a', 'ses-1')).toBe(true); + t.expect(store.sessions.delete('ws-a', 'ses-1')).toBe(false); + t.expect(store.sessions.get('ws-a', 'ses-1')).toBeNull(); + }); +} diff --git a/packages/application/tests/fixtures.ts b/packages/application/tests/fixtures.ts new file mode 100644 index 0000000..37b8109 --- /dev/null +++ b/packages/application/tests/fixtures.ts @@ -0,0 +1,74 @@ +import type { GraphRevision } from '@archwise/domain'; +import type { Clock, Digest, IdGenerator } from '../src/index.js'; + +export type BuildIds = { + revisionId: string; + workspaceId: string; + parentRevisionId: string | null; + createdAt: string; +}; + +/** Synthetic revision with `modules` module nodes; no user source or credentials. */ +export function buildRevision(modules: number) { + return (ids: BuildIds): GraphRevision => ({ + id: ids.revisionId, + workspaceId: ids.workspaceId, + parentRevisionId: ids.parentRevisionId, + createdAt: ids.createdAt, + status: 'complete', + repositories: [{ id: 'repo-root', label: 'fixture' }], + coverage: [ + { + repositoryId: 'repo-root', + analyzerId: 'node-manifest', + analyzerVersion: '1.0.0', + status: 'complete', + }, + ], + evidence: [ + { + id: 'ev-1', + repositoryId: 'repo-root', + analyzerId: 'node-manifest', + analyzerVersion: '1.0.0', + ruleId: 'package-manifest', + path: 'package.json', + lines: null, + }, + ], + nodes: Array.from({ length: modules }, (_, i) => ({ + id: `mod-${i}`, + kind: 'module' as const, + label: `Module ${i}`, + repositoryId: 'repo-root', + confidence: { level: 'observed' as const, reasons: ['manifest-declared'] }, + evidenceIds: ['ev-1'], + })), + edges: [], + diagnostics: [], + }); +} + +export function fakeClock(): Clock { + let second = 0; + return { + now: () => new Date(Date.UTC(2026, 10, 16, 0, 0, second++)).toISOString(), + }; +} + +export function sequentialIds(): IdGenerator { + let counter = 0; + return { next: (prefix) => `${prefix}-${String(++counter).padStart(24, '0')}` }; +} + +export const identityDigest: Digest = { sha256Hex: (text) => text }; + +export const sandboxDoc = (components: number, snapshots = false): string => + JSON.stringify({ + format: 'archwise-sandbox', + version: 1, + projectSignature: 'sig', + nodes: Array.from({ length: components }, (_, i) => ({ id: `sandbox-${i}` })), + connections: [], + draft: { savedA: snapshots ? {} : null, savedB: null }, + }); diff --git a/packages/application/tests/memory-store.contract.test.ts b/packages/application/tests/memory-store.contract.test.ts new file mode 100644 index 0000000..c9b38cb --- /dev/null +++ b/packages/application/tests/memory-store.contract.test.ts @@ -0,0 +1,8 @@ +import { expect, test } from 'vitest'; +import { createMemoryStore } from '../src/index.js'; +import { defineStoreContract } from '../src/testing/index.js'; + +defineStoreContract('memory', () => ({ store: createMemoryStore(), dispose() {} }), { + test, + expect, +}); diff --git a/packages/application/tests/sandbox-text.test.ts b/packages/application/tests/sandbox-text.test.ts new file mode 100644 index 0000000..36f73be --- /dev/null +++ b/packages/application/tests/sandbox-text.test.ts @@ -0,0 +1,37 @@ +import { expect, test } from 'vitest'; +import { inspectSandboxText, MAX_SANDBOX_BYTES } from '../src/index.js'; + +test('summarizes a minimal valid sandbox document', () => { + expect( + inspectSandboxText( + '{"format":"archwise-sandbox","version":1,"nodes":[{}],"draft":{"savedA":null,"savedB":{}}}', + ), + ).toEqual({ ok: true, summary: { componentCount: 1, hasSnapshots: true } }); +}); + +test('reports no snapshots when both slots are null', () => { + expect( + inspectSandboxText( + '{"format":"archwise-sandbox","version":1,"nodes":[],"draft":{"savedA":null,"savedB":null}}', + ), + ).toEqual({ ok: true, summary: { componentCount: 0, hasSnapshots: false } }); +}); + +test.each([ + 'not json', + '[]', + 'null', + '{"format":"other","version":1,"nodes":[],"draft":{}}', + '{"format":"archwise-sandbox","version":2,"nodes":[],"draft":{}}', + '{"format":"archwise-sandbox","version":1,"nodes":{},"draft":{}}', + '{"format":"archwise-sandbox","version":1,"nodes":[]}', + '{"format":"archwise-sandbox","version":1,"nodes":[],"draft":[]}', + '{"__proto__":{}}', +])('rejects %s without throwing', (text) => { + expect(inspectSandboxText(text)).toEqual({ ok: false, code: 'invalid-sandbox' }); +}); + +test('rejects documents above the byte limit', () => { + const padding = ' '.repeat(MAX_SANDBOX_BYTES + 1); + expect(inspectSandboxText(`${padding}{}`)).toEqual({ ok: false, code: 'too-large' }); +}); diff --git a/packages/application/tests/session-service.test.ts b/packages/application/tests/session-service.test.ts new file mode 100644 index 0000000..8528f1b --- /dev/null +++ b/packages/application/tests/session-service.test.ts @@ -0,0 +1,184 @@ +import { expect, test } from 'vitest'; +import { + createMemoryStore, + RevisionInvalidError, + SessionService, + type Store, +} from '../src/index.js'; +import { buildRevision, fakeClock, identityDigest, sandboxDoc, sequentialIds } from './fixtures.js'; + +const deps = (store: Store = createMemoryStore()) => ({ + store, + clock: fakeClock(), + ids: sequentialIds(), + digest: identityDigest, +}); + +const open = (d: ReturnType, modules = 1, rootPath = '/fixture/root') => { + const result = SessionService.open(d, { + rootPath, + view: '{"version":1}', + viewIdentity: 'v1', + build: buildRevision(modules), + }); + if (!result.ok) throw new Error(result.error); + return result.value; +}; + +test('an unchanged discovery reuses the latest revision', () => { + const d = deps(); + const first = open(d); + const second = open(d); + expect(second.currentRevisionId).toBe(first.currentRevisionId); +}); + +test('a changed discovery creates a child revision', () => { + const d = deps(); + const first = open(d, 1); + const second = open(d, 2); + expect(second.currentRevisionId).not.toBe(first.currentRevisionId); + const stored = d.store.revisions.get(second.workspaceId, second.currentRevisionId); + expect(stored?.revision.parentRevisionId).toBe(first.currentRevisionId); +}); + +test('sessions are persisted only after the first save', () => { + const service = open(deps()); + const reserved = service.current(); + expect(reserved.persisted).toBe(false); + expect(service.list()).toEqual([]); + expect(service.get(reserved.id)).toEqual({ ok: false, error: 'not-found' }); + + const saved = service.saveSandbox(reserved.id, sandboxDoc(1)); + expect(saved.ok && saved.value.label).toBe('Sandbox · 1 component'); + expect(service.current()).toEqual({ id: reserved.id, persisted: true }); + expect(service.list().map((s) => s.id)).toEqual([reserved.id]); +}); + +test('labels pluralize component counts', () => { + const service = open(deps()); + const saved = service.saveSandbox(service.current().id, sandboxDoc(3, true)); + expect(saved.ok && saved.value).toMatchObject({ + label: 'Sandbox · 3 components', + componentCount: 3, + hasSnapshots: true, + }); +}); + +test('a resumed session keeps its base revision after newer discoveries', () => { + const d = deps(); + const before = open(d, 1); + const sessionId = before.current().id; + before.saveSandbox(sessionId, sandboxDoc(1)); + + const after = open(d, 2); + const resumed = after.resume(sessionId); + expect(resumed.ok && resumed.value.baseIsCurrent).toBe(false); + expect(after.current()).toEqual({ id: sessionId, persisted: true }); + + after.saveSandbox(sessionId, sandboxDoc(2)); + const stored = d.store.sessions.get(after.workspaceId, sessionId); + expect(stored?.baseRevisionId).toBe(before.currentRevisionId); + const detail = after.get(sessionId); + expect(detail.ok && detail.value).toMatchObject({ componentCount: 2, baseIsCurrent: false }); +}); + +test('resumed details carry the sandbox and the base revision view', () => { + const service = open(deps()); + const id = service.current().id; + service.saveSandbox(id, sandboxDoc(1)); + const detail = service.resume(id); + expect(detail.ok && detail.value).toMatchObject({ + sandbox: sandboxDoc(1), + view: '{"version":1}', + baseIsCurrent: true, + }); +}); + +test('rename validates labels', () => { + const service = open(deps()); + const id = service.current().id; + service.saveSandbox(id, sandboxDoc(1)); + expect(service.rename(id, '')).toEqual({ ok: false, error: 'invalid-label' }); + expect(service.rename(id, 'AKIA' + 'ABCDEFGHIJKLMNOP')).toEqual({ + ok: false, + error: 'invalid-label', + }); + const renamed = service.rename(id, 'Cache experiment'); + expect(renamed.ok && renamed.value.label).toBe('Cache experiment'); +}); + +test('invalid sandbox text is rejected and nothing is persisted', () => { + const service = open(deps()); + expect(service.saveSandbox(service.current().id, '{}')).toEqual({ + ok: false, + error: 'invalid-sandbox', + }); + expect(service.list()).toEqual([]); +}); + +test('deleting the current session reserves a fresh one', () => { + const service = open(deps()); + const id = service.current().id; + service.saveSandbox(id, sandboxDoc(1)); + expect(service.delete(id)).toEqual({ ok: true, value: null }); + expect(service.current().id).not.toBe(id); + expect(service.current().persisted).toBe(false); + expect(service.list()).toEqual([]); +}); + +test.each(['get', 'resume', 'delete'] as const)('%s of an unknown id is not-found', (method) => { + const service = open(deps()); + expect(service[method]('ses-unknown')).toEqual({ ok: false, error: 'not-found' }); +}); + +test('saving to an unknown, non-current id is not-found', () => { + const service = open(deps()); + expect(service.saveSandbox('ses-unknown', sandboxDoc(1))).toEqual({ + ok: false, + error: 'not-found', + }); + expect(service.rename('ses-unknown', 'x')).toEqual({ ok: false, error: 'not-found' }); +}); + +test('sessions are isolated per workspace', () => { + const d = deps(); + const a = open(d, 1, '/fixture/a'); + a.saveSandbox(a.current().id, sandboxDoc(1)); + const b = open(d, 1, '/fixture/b'); + expect(b.list()).toEqual([]); + expect(b.get(a.current().id)).toEqual({ ok: false, error: 'not-found' }); +}); + +test('an invalid discovered revision throws RevisionInvalidError', () => { + const d = deps(); + expect(() => + SessionService.open(d, { + rootPath: '/fixture', + view: '{}', + viewIdentity: '{}', + build: (ids) => ({ ...buildRevision(1)(ids), createdAt: 'yesterday' }), + }), + ).toThrow(RevisionInvalidError); +}); + +test('a changed view with an unchanged revision records a new revision', () => { + const d = deps(); + const openWith = (viewIdentity: string) => { + const result = SessionService.open(d, { + rootPath: '/fixture/root', + view: `{"framework":"${viewIdentity}"}`, + viewIdentity, + build: buildRevision(1), + }); + if (!result.ok) throw new Error(result.error); + return result.value; + }; + const before = openWith('none'); + const same = openWith('none'); + const after = openWith('react'); + expect(same.currentRevisionId).toBe(before.currentRevisionId); + expect(after.currentRevisionId).not.toBe(before.currentRevisionId); + expect(d.store.revisions.get(after.workspaceId, after.currentRevisionId)?.view).toBe( + '{"framework":"react"}', + ); +}); diff --git a/packages/storage/README.md b/packages/storage/README.md new file mode 100644 index 0000000..b71e7e6 --- /dev/null +++ b/packages/storage/README.md @@ -0,0 +1,20 @@ +# @archwise/storage + +Local SQLite store, built on Node's built-in `node:sqlite`. It implements the `@archwise/application` store ports (workspaces, revisions and sessions). + +- `resolveDataDir(env, platform, home)` returns the OS application-data directory: + - macOS: `~/Library/Application Support/Archwise` + - Linux: `$XDG_DATA_HOME/archwise`, else `~/.local/share/archwise` + - Windows: `%LOCALAPPDATA%\Archwise` + - `ARCHWISE_DATA_DIR` overrides all of these. The store never writes inside analyzed repositories. +- `openStore(dataDir)` opens `archwise.db` (directory mode `0700`). It: + 1. runs an integrity check through a read-only connection; a corrupt file and its `-wal`/`-shm` companions are renamed to `archwise.db.corrupt-` and a fresh store starts; + 2. refuses files from a newer Archwise (`newer-schema`); + 3. backs up the file before migrating, to `archwise.db.backup-v-`, keeping the three newest backups; + 4. applies migrations in one transaction; on failure it rolls back, leaves the file unchanged and reports `migration-failed`; + 5. enables WAL. Every connection sets a 5-second busy timeout before any other work, so processes can share the file even while it is being created or migrated. +- Revisions are stored as canonical `archwise.graph` JSON and read back through the strict importer. Sessions store `archwise-sandbox` v1 text. + +The store contains absolute workspace root paths and Sandbox content. It is local-only and is never exported or returned by the API. + +Tests run the shared store contract from `@archwise/application/testing` against SQLite, plus lifecycle tests for migrations, backups, quarantine, refusal cases and two-handle concurrency. Run `pnpm --filter @archwise/storage test` after `pnpm build`. diff --git a/packages/storage/package.json b/packages/storage/package.json new file mode 100644 index 0000000..981b458 --- /dev/null +++ b/packages/storage/package.json @@ -0,0 +1,26 @@ +{ + "name": "@archwise/storage", + "version": "0.1.0-dev.0", + "private": true, + "type": "module", + "license": "Apache-2.0", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "files": [ + "dist" + ], + "scripts": { + "build": "tsc -p tsconfig.json", + "typecheck": "tsc -p tsconfig.check.json --noEmit", + "test": "vitest run" + }, + "dependencies": { + "@archwise/application": "workspace:*", + "@archwise/domain": "workspace:*", + "@archwise/schemas": "workspace:*" + } +} diff --git a/packages/storage/src/data-dir.ts b/packages/storage/src/data-dir.ts new file mode 100644 index 0000000..f4cadf7 --- /dev/null +++ b/packages/storage/src/data-dir.ts @@ -0,0 +1,21 @@ +import { posix, win32 } from 'node:path'; + +/** + * OS-appropriate application-data directory. Never inside an analyzed repository. + * `ARCHWISE_DATA_DIR` overrides the default (used by tests and by users who relocate data). + */ +export function resolveDataDir( + env: Readonly>, + platform: NodeJS.Platform, + home: string, +): string { + const override = env.ARCHWISE_DATA_DIR; + if (override) return override; + if (platform === 'win32') { + return win32.join(env.LOCALAPPDATA ?? win32.join(home, 'AppData', 'Local'), 'Archwise'); + } + if (platform === 'darwin') return posix.join(home, 'Library', 'Application Support', 'Archwise'); + return env.XDG_DATA_HOME + ? posix.join(env.XDG_DATA_HOME, 'archwise') + : posix.join(home, '.local', 'share', 'archwise'); +} diff --git a/packages/storage/src/index.ts b/packages/storage/src/index.ts new file mode 100644 index 0000000..622c4c0 --- /dev/null +++ b/packages/storage/src/index.ts @@ -0,0 +1,3 @@ +export * from './data-dir.js'; +export * from './migrations.js'; +export * from './sqlite-store.js'; diff --git a/packages/storage/src/migrations.ts b/packages/storage/src/migrations.ts new file mode 100644 index 0000000..cc8d036 --- /dev/null +++ b/packages/storage/src/migrations.ts @@ -0,0 +1,39 @@ +export interface Migration { + readonly version: number; + readonly sql: string; +} + +/** Ordered schema migrations. Never edit an applied migration; append a new version instead. */ +export const MIGRATIONS: readonly Migration[] = [ + { + version: 1, + sql: ` + CREATE TABLE workspaces ( + id TEXT PRIMARY KEY, + root_path TEXT NOT NULL UNIQUE, + created_at TEXT NOT NULL + ); + CREATE TABLE revisions ( + id TEXT PRIMARY KEY, + workspace_id TEXT NOT NULL REFERENCES workspaces(id), + fingerprint TEXT NOT NULL, + created_at TEXT NOT NULL, + document TEXT NOT NULL, + view_document TEXT NOT NULL + ); + CREATE INDEX revisions_by_workspace ON revisions(workspace_id, created_at); + CREATE TABLE sessions ( + id TEXT PRIMARY KEY, + workspace_id TEXT NOT NULL REFERENCES workspaces(id), + base_revision_id TEXT NOT NULL REFERENCES revisions(id), + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + label TEXT NOT NULL, + sandbox_document TEXT NOT NULL + ); + CREATE INDEX sessions_by_workspace ON sessions(workspace_id, updated_at); + `, + }, +]; + +export const SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1]!.version; diff --git a/packages/storage/src/sqlite-store.ts b/packages/storage/src/sqlite-store.ts new file mode 100644 index 0000000..4bc6b81 --- /dev/null +++ b/packages/storage/src/sqlite-store.ts @@ -0,0 +1,358 @@ +import type { + SessionChanges, + Store, + StoredRevision, + StoredSession, + Workspace, +} from '@archwise/application'; +import { importGraphJson, serializeGraphRevision } from '@archwise/schemas'; +import { + accessSync, + constants, + existsSync, + mkdirSync, + readdirSync, + renameSync, + rmSync, + statSync, +} from 'node:fs'; +import { join } from 'node:path'; +import { backup, DatabaseSync } from 'node:sqlite'; +import { MIGRATIONS, type Migration } from './migrations.js'; + +export type StoreUnavailableReason = 'newer-schema' | 'migration-failed' | 'unwritable'; + +/** The store cannot be used safely; the file (if any) was left unchanged. */ +export class StoreUnavailableError extends Error { + readonly reason: StoreUnavailableReason; + constructor(reason: StoreUnavailableReason) { + super(`Archwise local store unavailable: ${reason}`); + this.name = 'StoreUnavailableError'; + this.reason = reason; + } +} + +export interface OpenedStore extends Store { + readonly path: string; + readonly quarantinedPath: string | null; + readonly backupPath: string | null; + close(): void; +} + +export interface OpenStoreOptions { + readonly now?: () => Date; + readonly migrations?: readonly Migration[]; +} + +const DB_FILE = 'archwise.db'; +const KEPT_BACKUPS = 3; +const CORRUPTION_CODES = new Set([11, 26]); // SQLITE_CORRUPT, SQLITE_NOTADB +const READONLY_CODE = 8; // SQLITE_READONLY +const BUSY_TIMEOUT_MS = 5000; +const COMPANION_SUFFIXES = ['-wal', '-shm'] as const; +const BACKUP_NAME = /^archwise\.db\.backup-v(\d+)-(.+)$/; + +/** Every connection waits for locks held by other Archwise processes before failing. */ +function connect(path: string): DatabaseSync { + const db = new DatabaseSync(path); + db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`); + return db; +} + +const stampOf = (date: Date): string => date.toISOString().replace(/:/g, '-'); + +const errcodeOf = (error: unknown): number | null => + typeof error === 'object' && error !== null && 'errcode' in error + ? (error as { errcode: number }).errcode + : null; + +const isCorruption = (error: unknown): boolean => CORRUPTION_CODES.has(errcodeOf(error) ?? -1); + +function ensureWritableDirectory(dataDir: string): void { + try { + mkdirSync(dataDir, { recursive: true, mode: 0o700 }); + if (!statSync(dataDir).isDirectory()) throw new Error('not a directory'); + accessSync(dataDir, constants.W_OK); + } catch { + throw new StoreUnavailableError('unwritable'); + } +} + +function schemaVersion(db: DatabaseSync): number { + const table = db + .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'") + .get(); + if (!table) return 0; + const row = db.prepare('SELECT MAX(version) AS version FROM schema_migrations').get() as { + version: number | null; + }; + return row.version ?? 0; +} + +/** + * Checks an existing file through a read-only connection, then opens it for writing. A + * read-write connection to a corrupt file would delete its WAL and shared-memory companions on + * close, losing committed frames before they could be quarantined. Returns null when corrupt. + */ +function openChecked(path: string): DatabaseSync | null { + let probe: DatabaseSync | undefined; + try { + probe = new DatabaseSync(path, { readOnly: true }); + probe.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`); + const rows = probe.prepare('PRAGMA integrity_check').all() as { integrity_check: string }[]; + if (rows.length !== 1 || rows[0]!.integrity_check !== 'ok') return null; + } catch (error) { + if (isCorruption(error)) return null; + throw error; + } finally { + probe?.close(); + } + return connect(path); +} + +/** Keeps the newest backups, ordered by schema version and then by timestamp. */ +export function pruneBackups(dataDir: string): void { + const backups = readdirSync(dataDir) + .map((name) => ({ name, match: BACKUP_NAME.exec(name) })) + .filter((entry): entry is { name: string; match: RegExpExecArray } => entry.match !== null) + .sort( + (a, b) => + Number(a.match[1]) - Number(b.match[1]) || + (a.match[2]! < b.match[2]! ? -1 : a.match[2]! > b.match[2]! ? 1 : 0), + ); + for (const { name } of backups.slice(0, Math.max(0, backups.length - KEPT_BACKUPS))) { + rmSync(join(dataDir, name), { force: true }); + } +} + +/** Moves a corrupt database and its WAL/shared-memory companions aside; nothing is deleted. */ +function quarantine(path: string, target: string): void { + renameSync(path, target); + for (const suffix of COMPANION_SUFFIXES) { + if (existsSync(`${path}${suffix}`)) renameSync(`${path}${suffix}`, `${target}${suffix}`); + } +} + +/** + * Applies pending migrations under a write lock. The version is re-read after acquiring the + * lock so a process that lost a race skips migrations another process already applied. + */ +function migrate(db: DatabaseSync, migrations: readonly Migration[], now: Date): void { + const target = migrations[migrations.length - 1]?.version ?? 0; + if (schemaVersion(db) >= target) return; + try { + db.exec('BEGIN IMMEDIATE'); + const pending = migrations.filter((migration) => migration.version > schemaVersion(db)); + db.exec( + 'CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)', + ); + for (const migration of pending) { + db.exec(migration.sql); + db.prepare('INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)').run( + migration.version, + now.toISOString(), + ); + } + db.exec('COMMIT'); + } catch (error) { + if (errcodeOf(error) === READONLY_CODE) throw new StoreUnavailableError('unwritable'); + try { + db.exec('ROLLBACK'); + } catch { + // The transaction may already be closed by SQLite. + } + throw new StoreUnavailableError('migration-failed'); + } +} + +/** + * Opens the local store: integrity check with quarantine, refusal of newer schemas, backup + * before migrating, transactional migrations, then WAL and a busy timeout for concurrent + * Archwise processes. WAL is enabled only after migrating so a failed migration leaves the + * original file bytes untouched. + */ +export async function openStore( + dataDir: string, + options: OpenStoreOptions = {}, +): Promise { + const now = options.now ?? (() => new Date()); + const migrations = options.migrations ?? MIGRATIONS; + const target = migrations[migrations.length - 1]?.version ?? 0; + ensureWritableDirectory(dataDir); + const path = join(dataDir, DB_FILE); + + let quarantinedPath: string | null = null; + let db: DatabaseSync | null = null; + if (existsSync(path)) { + try { + accessSync(path, constants.W_OK); + } catch { + throw new StoreUnavailableError('unwritable'); + } + db = openChecked(path); + if (!db) { + quarantinedPath = `${path}.corrupt-${stampOf(now())}`; + quarantine(path, quarantinedPath); + } + } + db ??= connect(path); + + let backupPath: string | null = null; + try { + const version = schemaVersion(db); + if (version > target) throw new StoreUnavailableError('newer-schema'); + if (version < target && quarantinedPath === null && statSync(path).size > 0) { + backupPath = `${path}.backup-v${version}-${stampOf(now())}`; + await backup(db, backupPath); + pruneBackups(dataDir); + } + migrate(db, migrations, now()); + db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON'); + } catch (error) { + db.close(); + if (errcodeOf(error) === READONLY_CODE) throw new StoreUnavailableError('unwritable'); + throw error; + } + return createSqliteStore(db, path, quarantinedPath, backupPath); +} + +interface RevisionRow { + id: string; + workspace_id: string; + fingerprint: string; + created_at: string; + document: string; + view_document: string; +} +interface SessionRow { + id: string; + workspace_id: string; + base_revision_id: string; + created_at: string; + updated_at: string; + label: string; + sandbox_document: string; +} + +function toRevision(row: RevisionRow | undefined): StoredRevision | null { + if (!row) return null; + const imported = importGraphJson(row.document); + if (!imported.ok) return null; + return { + id: row.id, + workspaceId: row.workspace_id, + fingerprint: row.fingerprint, + createdAt: row.created_at, + revision: imported.value, + view: row.view_document, + }; +} + +function toSession(row: SessionRow | undefined): StoredSession | null { + if (!row) return null; + return { + id: row.id, + workspaceId: row.workspace_id, + baseRevisionId: row.base_revision_id, + createdAt: row.created_at, + updatedAt: row.updated_at, + label: row.label, + sandbox: row.sandbox_document, + }; +} + +function createSqliteStore( + db: DatabaseSync, + path: string, + quarantinedPath: string | null, + backupPath: string | null, +): OpenedStore { + const q = { + findWorkspace: db.prepare( + 'SELECT id, root_path, created_at FROM workspaces WHERE root_path = ?', + ), + insertWorkspace: db.prepare( + 'INSERT INTO workspaces (id, root_path, created_at) VALUES (?, ?, ?) ON CONFLICT(root_path) DO NOTHING', + ), + latestRevision: db.prepare( + 'SELECT * FROM revisions WHERE workspace_id = ? ORDER BY created_at DESC, id DESC LIMIT 1', + ), + getRevision: db.prepare('SELECT * FROM revisions WHERE workspace_id = ? AND id = ?'), + insertRevision: db.prepare( + 'INSERT INTO revisions (id, workspace_id, fingerprint, created_at, document, view_document) VALUES (?, ?, ?, ?, ?, ?)', + ), + getSession: db.prepare('SELECT * FROM sessions WHERE workspace_id = ? AND id = ?'), + listSessions: db.prepare( + 'SELECT * FROM sessions WHERE workspace_id = ? ORDER BY updated_at DESC, id ASC', + ), + insertSession: db.prepare( + 'INSERT INTO sessions (id, workspace_id, base_revision_id, created_at, updated_at, label, sandbox_document) VALUES (?, ?, ?, ?, ?, ?, ?)', + ), + updateSession: db.prepare( + 'UPDATE sessions SET sandbox_document = COALESCE(?, sandbox_document), label = COALESCE(?, label), updated_at = ? WHERE workspace_id = ? AND id = ?', + ), + deleteSession: db.prepare('DELETE FROM sessions WHERE workspace_id = ? AND id = ?'), + }; + + return { + path, + quarantinedPath, + backupPath, + close: () => db.close(), + workspaces: { + resolve(rootPath, id, createdAt): Workspace { + q.insertWorkspace.run(id, rootPath, createdAt); + const row = q.findWorkspace.get(rootPath) as + { id: string; root_path: string; created_at: string } | undefined; + if (!row) throw new Error('Workspace resolution failed'); + return { id: row.id, rootPath: row.root_path, createdAt: row.created_at }; + }, + }, + revisions: { + latest: (workspaceId) => + toRevision(q.latestRevision.get(workspaceId) as RevisionRow | undefined), + get: (workspaceId, id) => + toRevision(q.getRevision.get(workspaceId, id) as RevisionRow | undefined), + insert(revision) { + const document = serializeGraphRevision(revision.revision); + if (!document.ok) throw new Error('Refusing to store an invalid revision'); + q.insertRevision.run( + revision.id, + revision.workspaceId, + revision.fingerprint, + revision.createdAt, + document.value, + revision.view, + ); + }, + }, + sessions: { + get: (workspaceId, id) => + toSession(q.getSession.get(workspaceId, id) as SessionRow | undefined), + list: (workspaceId) => + (q.listSessions.all(workspaceId) as unknown as SessionRow[]).map((row) => toSession(row)!), + insert(session) { + q.insertSession.run( + session.id, + session.workspaceId, + session.baseRevisionId, + session.createdAt, + session.updatedAt, + session.label, + session.sandbox, + ); + }, + update(workspaceId, id, changes: SessionChanges) { + const result = q.updateSession.run( + changes.sandbox ?? null, + changes.label ?? null, + changes.updatedAt, + workspaceId, + id, + ); + return Number(result.changes) > 0; + }, + delete: (workspaceId, id) => Number(q.deleteSession.run(workspaceId, id).changes) > 0, + }, + }; +} diff --git a/packages/storage/tests/data-dir.test.ts b/packages/storage/tests/data-dir.test.ts new file mode 100644 index 0000000..16f8613 --- /dev/null +++ b/packages/storage/tests/data-dir.test.ts @@ -0,0 +1,28 @@ +import { expect, test } from 'vitest'; +import { resolveDataDir } from '../src/index.js'; + +test('ARCHWISE_DATA_DIR overrides every platform default', () => { + expect(resolveDataDir({ ARCHWISE_DATA_DIR: '/custom/store' }, 'darwin', '/Users/u')).toBe( + '/custom/store', + ); +}); + +test('macOS uses Application Support', () => { + expect(resolveDataDir({}, 'darwin', '/Users/u')).toBe( + '/Users/u/Library/Application Support/Archwise', + ); +}); + +test('Linux prefers XDG_DATA_HOME, then ~/.local/share', () => { + expect(resolveDataDir({ XDG_DATA_HOME: '/xdg' }, 'linux', '/home/u')).toBe('/xdg/archwise'); + expect(resolveDataDir({}, 'linux', '/home/u')).toBe('/home/u/.local/share/archwise'); +}); + +test('Windows uses LOCALAPPDATA', () => { + expect( + resolveDataDir({ LOCALAPPDATA: 'C:\\Users\\u\\AppData\\Local' }, 'win32', 'C:\\Users\\u'), + ).toBe('C:\\Users\\u\\AppData\\Local\\Archwise'); + expect(resolveDataDir({}, 'win32', 'C:\\Users\\u')).toBe( + 'C:\\Users\\u\\AppData\\Local\\Archwise', + ); +}); diff --git a/packages/storage/tests/helpers.ts b/packages/storage/tests/helpers.ts new file mode 100644 index 0000000..721a15b --- /dev/null +++ b/packages/storage/tests/helpers.ts @@ -0,0 +1,8 @@ +import { mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +export function tempDir(): { path: string; dispose(): void } { + const path = mkdtempSync(join(tmpdir(), 'archwise-store-')); + return { path, dispose: () => rmSync(path, { recursive: true, force: true }) }; +} diff --git a/packages/storage/tests/lifecycle.test.ts b/packages/storage/tests/lifecycle.test.ts new file mode 100644 index 0000000..32f4ebd --- /dev/null +++ b/packages/storage/tests/lifecycle.test.ts @@ -0,0 +1,270 @@ +import { + chmodSync, + existsSync, + mkdirSync, + readdirSync, + readFileSync, + writeFileSync, +} from 'node:fs'; +import { join } from 'node:path'; +import { DatabaseSync } from 'node:sqlite'; +import { afterEach, expect, test } from 'vitest'; +import { openStore, pruneBackups, SCHEMA_VERSION, StoreUnavailableError } from '../src/index.js'; +import { tempDir } from './helpers.js'; + +const cleanups: (() => void)[] = []; +afterEach(() => { + while (cleanups.length) cleanups.pop()!(); +}); +const dir = () => { + const d = tempDir(); + cleanups.push(d.dispose); + return d.path; +}; +const dbPath = (d: string) => join(d, 'archwise.db'); +const versionOf = (path: string): number => { + const db = new DatabaseSync(path); + try { + return (db.prepare('SELECT MAX(version) AS v FROM schema_migrations').get() as { v: number }).v; + } finally { + db.close(); + } +}; + +async function expectUnavailable(promise: Promise, reason: string) { + const error = await promise.then( + () => null, + (e: unknown) => e, + ); + expect(error).toBeInstanceOf(StoreUnavailableError); + expect((error as StoreUnavailableError).reason).toBe(reason); +} + +test('a fresh open creates the database at the current schema version', async () => { + const d = dir(); + const store = await openStore(d); + store.close(); + expect(existsSync(dbPath(d))).toBe(true); + expect(versionOf(dbPath(d))).toBe(SCHEMA_VERSION); + expect(store.backupPath).toBeNull(); + expect(store.quarantinedPath).toBeNull(); +}); + +test('reopening an up-to-date store does not create a backup', async () => { + const d = dir(); + (await openStore(d)).close(); + const again = await openStore(d); + again.close(); + expect(again.backupPath).toBeNull(); + expect(readdirSync(d).some((name) => name.includes('.backup-'))).toBe(false); +}); + +test('migrating an older database writes a backup first', async () => { + const d = dir(); + const legacy = new DatabaseSync(dbPath(d)); + legacy.exec("CREATE TABLE legacy(x TEXT); INSERT INTO legacy VALUES ('kept')"); + legacy.close(); + + const store = await openStore(d); + store.close(); + expect(store.backupPath).not.toBeNull(); + const backup = new DatabaseSync(store.backupPath!); + try { + expect(backup.prepare('SELECT x FROM legacy').get()).toEqual({ x: 'kept' }); + } finally { + backup.close(); + } + expect(versionOf(dbPath(d))).toBe(SCHEMA_VERSION); +}); + +test('a database from a newer Archwise is refused untouched', async () => { + const d = dir(); + const future = new DatabaseSync(dbPath(d)); + future.exec( + "CREATE TABLE schema_migrations(version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL); INSERT INTO schema_migrations VALUES (99, '2030-01-01T00:00:00.000Z')", + ); + future.close(); + const before = readFileSync(dbPath(d)); + await expectUnavailable(openStore(d), 'newer-schema'); + expect(readFileSync(dbPath(d)).equals(before)).toBe(true); +}); + +test('a corrupt file is quarantined and a fresh store starts', async () => { + const d = dir(); + writeFileSync(dbPath(d), 'not a database '.repeat(300)); + const store = await openStore(d); + try { + expect(store.quarantinedPath).not.toBeNull(); + expect(readFileSync(store.quarantinedPath!, 'utf8')).toContain('not a database'); + store.workspaces.resolve('/root', 'ws-1', '2026-11-16T00:00:00.000Z'); + } finally { + store.close(); + } + expect(versionOf(dbPath(d))).toBe(SCHEMA_VERSION); +}); + +test('a failing migration rolls back and leaves the file unchanged', async () => { + const d = dir(); + const legacy = new DatabaseSync(dbPath(d)); + legacy.exec("CREATE TABLE legacy(x TEXT); INSERT INTO legacy VALUES ('kept')"); + legacy.close(); + const before = readFileSync(dbPath(d)); + await expectUnavailable( + openStore(d, { + migrations: [{ version: 1, sql: 'CREATE TABLE ok(a TEXT); THIS IS NOT SQL;' }], + }), + 'migration-failed', + ); + expect(readFileSync(dbPath(d)).equals(before)).toBe(true); +}); + +test.skipIf(process.platform === 'win32' || process.getuid?.() === 0)( + 'an unwritable data directory is reported as unwritable', + async () => { + const parent = dir(); + const locked = join(parent, 'locked'); + mkdirSync(locked); + chmodSync(locked, 0o500); + cleanups.push(() => chmodSync(locked, 0o700)); + await expectUnavailable(openStore(join(locked, 'store')), 'unwritable'); + }, +); + +test('a data directory path that is a file is reported as unwritable', async () => { + const parent = dir(); + const file = join(parent, 'not-a-directory'); + writeFileSync(file, 'x'); + await expectUnavailable(openStore(file), 'unwritable'); +}); + +test('two handles on the same file can interleave writes', async () => { + const d = dir(); + const a = await openStore(d); + const b = await openStore(d); + try { + a.workspaces.resolve('/root', 'ws-1', '2026-11-16T00:00:00.000Z'); + a.revisions.insert({ + id: 'rev-1', + workspaceId: 'ws-1', + fingerprint: 'fp', + createdAt: '2026-11-16T00:00:00.000Z', + revision: { + id: 'rev-1', + workspaceId: 'ws-1', + parentRevisionId: null, + createdAt: '2026-11-16T00:00:00.000Z', + status: 'partial', + repositories: [], + coverage: [], + evidence: [], + nodes: [], + edges: [], + diagnostics: [], + }, + view: '{}', + }); + a.sessions.insert({ + id: 'ses-1', + workspaceId: 'ws-1', + baseRevisionId: 'rev-1', + createdAt: '2026-11-16T00:00:00.000Z', + updatedAt: '2026-11-16T00:00:00.000Z', + label: 'Shared', + sandbox: '{}', + }); + for (let i = 0; i < 50; i++) { + const handle = i % 2 === 0 ? a : b; + const stamp = new Date(Date.UTC(2026, 10, 16, 0, 1, i)).toISOString(); + expect( + handle.sessions.update('ws-1', 'ses-1', { label: `Write ${i}`, updatedAt: stamp }), + ).toBe(true); + } + expect(b.sessions.get('ws-1', 'ses-1')?.label).toBe('Write 49'); + } finally { + a.close(); + b.close(); + } +}); + +test('parallel first opens from separate threads all succeed', async () => { + const { Worker } = await import('node:worker_threads'); + const { pathToFileURL } = await import('node:url'); + const d = dir(); + const entry = pathToFileURL(join(import.meta.dirname, '../dist/index.js')).href; + const code = ` + const { workerData, parentPort } = require('node:worker_threads'); + import(workerData.entry).then(async ({ openStore }) => { + try { + const store = await openStore(workerData.dir); + store.close(); + parentPort.postMessage('ok'); + } catch (error) { + parentPort.postMessage(String(error && (error.reason || error.message))); + } + }); + `; + for (let trial = 0; trial < 3; trial++) { + const trialDir = join(d, `trial-${trial}`); + const results = await Promise.all( + Array.from( + { length: 4 }, + () => + new Promise((accept) => { + const worker = new Worker(code, { eval: true, workerData: { entry, dir: trialDir } }); + worker.once('message', (message: string) => { + accept(message); + void worker.terminate(); + }); + }), + ), + ); + expect(results).toEqual(['ok', 'ok', 'ok', 'ok']); + expect(versionOf(join(trialDir, 'archwise.db'))).toBe(SCHEMA_VERSION); + } +}); + +test('quarantine moves WAL and shared-memory companions with the corrupt file', async () => { + const d = dir(); + writeFileSync(dbPath(d), 'not a database '.repeat(300)); + writeFileSync(`${dbPath(d)}-wal`, 'committed frames'); + writeFileSync(`${dbPath(d)}-shm`, 'shared memory'); + const store = await openStore(d); + store.close(); + expect(readFileSync(`${store.quarantinedPath!}-wal`, 'utf8')).toBe('committed frames'); + // -shm is a rebuildable shared-memory index (no durable data); it must move, not survive intact. + expect(existsSync(`${store.quarantinedPath!}-shm`)).toBe(true); + expect(existsSync(`${dbPath(d)}-wal`)).toBe(false); +}); + +test('backup pruning keeps the newest backups by schema version, then time', () => { + const d = dir(); + const names = [ + 'archwise.db.backup-v9-2026-11-16T00-00-00.000Z', + 'archwise.db.backup-v10-2026-11-15T00-00-00.000Z', + 'archwise.db.backup-v10-2026-11-17T00-00-00.000Z', + 'archwise.db.backup-v2-2026-12-01T00-00-00.000Z', + 'archwise.db.backup-v11-2026-11-18T00-00-00.000Z', + ]; + for (const name of names) writeFileSync(join(d, name), 'x'); + pruneBackups(d); + expect(readdirSync(d).sort()).toEqual( + [ + 'archwise.db.backup-v10-2026-11-15T00-00-00.000Z', + 'archwise.db.backup-v10-2026-11-17T00-00-00.000Z', + 'archwise.db.backup-v11-2026-11-18T00-00-00.000Z', + ].sort(), + ); +}); + +test.skipIf(process.platform === 'win32' || process.getuid?.() === 0)( + 'a read-only store file is reported as unwritable', + async () => { + const d = dir(); + (await openStore(d)).close(); + for (const suffix of ['', '-wal', '-shm']) { + if (existsSync(`${dbPath(d)}${suffix}`)) chmodSync(`${dbPath(d)}${suffix}`, 0o400); + } + cleanups.push(() => chmodSync(dbPath(d), 0o600)); + await expectUnavailable(openStore(d), 'unwritable'); + }, +); diff --git a/packages/storage/tests/sqlite.contract.test.ts b/packages/storage/tests/sqlite.contract.test.ts new file mode 100644 index 0000000..fe4b2ed --- /dev/null +++ b/packages/storage/tests/sqlite.contract.test.ts @@ -0,0 +1,20 @@ +import { defineStoreContract } from '@archwise/application/testing'; +import { expect, test } from 'vitest'; +import { openStore } from '../src/index.js'; +import { tempDir } from './helpers.js'; + +defineStoreContract( + 'sqlite', + async () => { + const dir = tempDir(); + const store = await openStore(dir.path); + return { + store, + dispose() { + store.close(); + dir.dispose(); + }, + }; + }, + { test, expect }, +); diff --git a/packages/storage/tsconfig.check.json b/packages/storage/tsconfig.check.json new file mode 100644 index 0000000..33f9a7d --- /dev/null +++ b/packages/storage/tsconfig.check.json @@ -0,0 +1,8 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "rootDir": ".", + "noEmit": true + }, + "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts"] +} diff --git a/packages/storage/tsconfig.json b/packages/storage/tsconfig.json new file mode 100644 index 0000000..df59da5 --- /dev/null +++ b/packages/storage/tsconfig.json @@ -0,0 +1,8 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "dist" + }, + "include": ["src/**/*.ts"] +} diff --git a/packages/storage/vitest.config.ts b/packages/storage/vitest.config.ts new file mode 100644 index 0000000..d569172 --- /dev/null +++ b/packages/storage/vitest.config.ts @@ -0,0 +1,2 @@ +import { defineConfig } from 'vitest/config'; +export default defineConfig({ test: { name: 'storage', include: ['tests/**/*.test.ts'] } }); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9fd9cd2..96c7d4f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -45,7 +45,20 @@ importers: specifier: 5.1.0 version: 5.1.0(@types/node@24.19.2)(jsdom@31.0.0)(vite@8.3.7(@types/node@24.19.2)(yaml@2.9.1)) - apps/cli: {} + apps/cli: + dependencies: + '@archwise/application': + specifier: workspace:* + version: link:../../packages/application + '@archwise/domain': + specifier: workspace:* + version: link:../../packages/domain + '@archwise/schemas': + specifier: workspace:* + version: link:../../packages/schemas + '@archwise/storage': + specifier: workspace:* + version: link:../../packages/storage apps/server: {} @@ -82,6 +95,9 @@ importers: '@archwise/domain': specifier: workspace:* version: link:../domain + '@archwise/schemas': + specifier: workspace:* + version: link:../schemas packages/domain: {} @@ -94,6 +110,18 @@ importers: specifier: 4.6.7 version: 4.6.7 + packages/storage: + dependencies: + '@archwise/application': + specifier: workspace:* + version: link:../application + '@archwise/domain': + specifier: workspace:* + version: link:../domain + '@archwise/schemas': + specifier: workspace:* + version: link:../schemas + packages/test-fixtures: {} packages: diff --git a/scripts/tests/boundaries.test.mjs b/scripts/tests/boundaries.test.mjs index 846c438..e5daf0a 100644 --- a/scripts/tests/boundaries.test.mjs +++ b/scripts/tests/boundaries.test.mjs @@ -90,3 +90,20 @@ test('rejects undeclared installed dependencies', async () => { assert.equal(result.status, 1, result.stdout + result.stderr); assert.match(result.stdout + result.stderr, /no-undeclared/); }); + +test('rejects storage imports of app code', async () => { + const result = await inspect({ + 'packages/storage/src/index.ts': "export { value } from '../../../apps/cli/src/index.js';", + 'apps/cli/src/index.ts': 'export const value = 1;', + }); + assert.equal(result.status, 1, result.stdout + result.stderr); + assert.match(result.stdout + result.stderr, /storage-inward-only/); +}); + +test('allows storage to use Node built-ins', async () => { + const result = await inspect({ + 'packages/storage/src/index.ts': + "import { join } from 'node:path'; export const p = join('a');", + }); + assert.equal(result.status, 0, result.stdout + result.stderr); +}); diff --git a/scripts/tests/session-store-integration.test.mjs b/scripts/tests/session-store-integration.test.mjs new file mode 100644 index 0000000..77b61c7 --- /dev/null +++ b/scripts/tests/session-store-integration.test.mjs @@ -0,0 +1,137 @@ +import assert from 'node:assert/strict'; +import { spawn, spawnSync } from 'node:child_process'; +import { existsSync } from 'node:fs'; +import { mkdtemp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { dirname, join, relative, resolve } from 'node:path'; +import { test } from 'node:test'; + +const cli = resolve('apps/cli/dist/bin.js'); + +async function snapshot(root) { + const entries = {}; + async function walk(dir) { + for (const entry of await readdir(dir, { withFileTypes: true })) { + const full = join(dir, entry.name); + if (entry.isDirectory()) await walk(full); + else entries[relative(root, full).split('\\').join('/')] = await readFile(full, 'base64'); + } + } + await walk(root); + return entries; +} + +async function fixture() { + const root = await mkdtemp(join(tmpdir(), 'archwise-session-fixture-')); + const files = { + 'package.json': JSON.stringify({ name: 'demo-root', private: true }), + 'apps/web/package.json': JSON.stringify({ + name: '@demo/web', + dependencies: { '@demo/core': '*' }, + }), + 'packages/core/package.json': JSON.stringify({ name: '@demo/core' }), + }; + for (const [path, content] of Object.entries(files)) { + await mkdir(dirname(join(root, path)), { recursive: true }); + await writeFile(join(root, path), content); + } + return root; +} + +const run = (args, env) => + spawnSync(process.execPath, [cli, ...args], { + encoding: 'utf8', + env: { ...process.env, ...env }, + timeout: 20_000, + }); + +/** Starts `--serve --no-open`, resolves with the bootstrap URL once printed. */ +function serve(root, env) { + const child = spawn(process.execPath, [cli, '--serve', '--no-open', '--path', root], { + env: { ...process.env, ...env }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + return new Promise((accept, reject) => { + let output = ''; + const timer = setTimeout(() => reject(new Error(`server did not start: ${output}`)), 20_000); + child.stdout.on('data', (chunk) => { + output += chunk; + const match = output.match(/Local session URL: (\S+)/); + if (match) { + clearTimeout(timer); + accept({ child, bootstrapUrl: match[1] }); + } + }); + child.stderr.on('data', (chunk) => (output += chunk)); + child.once('exit', (code) => reject(new Error(`server exited ${code}: ${output}`))); + }); +} + +test('sessions persist across launches without touching the analyzed tree', async () => { + const root = await fixture(); + const dataDir = await mkdtemp(join(tmpdir(), 'archwise-session-data-')); + const env = { ARCHWISE_DATA_DIR: dataDir }; + let server; + try { + const before = await snapshot(root); + const empty = run(['--sessions', '--path', root], env); + assert.equal(empty.status, 0, empty.stderr); + assert.match(empty.stdout, /No saved sessions for this project\./); + + server = await serve(root, env); + const origin = new URL(server.bootstrapUrl).origin; + const bootstrap = await fetch(server.bootstrapUrl, { redirect: 'manual' }); + const cookie = bootstrap.headers.get('set-cookie').split(';')[0]; + const current = await ( + await fetch(`${origin}/api/v1/sessions/current`, { headers: { cookie } }) + ).json(); + assert.equal(current.storeEnabled, true); + const sandbox = JSON.stringify({ + format: 'archwise-sandbox', + version: 1, + projectSignature: 'sig', + nodes: [{ id: 'sandbox-1' }, { id: 'sandbox-2' }], + connections: [], + draft: { savedA: {}, savedB: null }, + }); + const saved = await fetch(`${origin}/api/v1/sessions/${current.id}/sandbox`, { + method: 'PUT', + headers: { cookie, origin, 'content-type': 'application/json' }, + body: sandbox, + }); + assert.equal(saved.status, 200); + server.child.kill(); + await new Promise((accept) => server.child.once('exit', accept)); + server = undefined; + + const listed = run(['--sessions', '--path', root], env); + assert.equal(listed.status, 0, listed.stderr); + assert.match(listed.stdout, /Sandbox · 2 components/); + assert.match(listed.stdout, /A\/B/); + assert.match(listed.stdout, new RegExp(current.id)); + + assert.deepEqual(await snapshot(root), before); + assert.ok(existsSync(join(dataDir, 'archwise.db'))); + } finally { + server?.child.kill(); + await rm(root, { recursive: true, force: true }); + await rm(dataDir, { recursive: true, force: true }); + } +}); + +test('an unusable data directory stops --serve with an actionable message', async () => { + const root = await fixture(); + const parent = await mkdtemp(join(tmpdir(), 'archwise-session-bad-')); + const notADirectory = join(parent, 'file'); + await writeFile(notADirectory, 'x'); + try { + const result = run(['--serve', '--no-open', '--path', root], { + ARCHWISE_DATA_DIR: notADirectory, + }); + assert.equal(result.status, 2, result.stdout + result.stderr); + assert.match(result.stderr, /ARCHWISE_DATA_DIR/); + } finally { + await rm(root, { recursive: true, force: true }); + await rm(parent, { recursive: true, force: true }); + } +});