From ced11827625386b1da6be1693c10a3b402d0829b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Oliveira?= Date: Sun, 15 Nov 2026 20:29:33 -0300 Subject: [PATCH 1/8] docs: specify sessions and local store (Phase 2, second slice) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Signed-off-by: André Oliveira --- ...6-11-16-sessions-and-local-store-design.md | 169 ++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-16-sessions-and-local-store-design.md 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. From bfc4e797989354af47a68c7f9b51016d4212e7d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Oliveira?= Date: Sun, 15 Nov 2026 20:31:56 -0300 Subject: [PATCH 2/8] docs: plan session store implementation (PR 1 of 2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Signed-off-by: André Oliveira --- .../plans/2026-11-16-session-store.md | 372 ++++++++++++++++++ 1 file changed, 372 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-16-session-store.md 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. From 8de8b65884849cdf07e1ed0ea2e13044a6c21ed9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Oliveira?= Date: Sun, 15 Nov 2026 20:34:09 -0300 Subject: [PATCH 3/8] feat(application): session service, store ports and contract suite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Signed-off-by: André Oliveira --- packages/application/package.json | 7 +- packages/application/src/index.ts | 6 + packages/application/src/memory-store.ts | 65 ++++++ packages/application/src/ports.ts | 78 +++++++ packages/application/src/sandbox-text.ts | 49 ++++ packages/application/src/session-service.ts | 215 ++++++++++++++++++ packages/application/src/testing/index.ts | 1 + .../application/src/testing/store-contract.ts | 126 ++++++++++ packages/application/tests/fixtures.ts | 74 ++++++ .../tests/memory-store.contract.test.ts | 8 + .../application/tests/sandbox-text.test.ts | 37 +++ .../application/tests/session-service.test.ts | 160 +++++++++++++ pnpm-lock.yaml | 3 + 13 files changed, 828 insertions(+), 1 deletion(-) create mode 100644 packages/application/src/memory-store.ts create mode 100644 packages/application/src/ports.ts create mode 100644 packages/application/src/sandbox-text.ts create mode 100644 packages/application/src/session-service.ts create mode 100644 packages/application/src/testing/index.ts create mode 100644 packages/application/src/testing/store-contract.ts create mode 100644 packages/application/tests/fixtures.ts create mode 100644 packages/application/tests/memory-store.contract.test.ts create mode 100644 packages/application/tests/sandbox-text.test.ts create mode 100644 packages/application/tests/session-service.test.ts 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..764e95e --- /dev/null +++ b/packages/application/src/session-service.ts @@ -0,0 +1,215 @@ +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; + 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 graph content, independent of revision identity, time and parent. */ +function fingerprint(revision: GraphRevision, 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); +} + +/** + * 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, 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..2ce873a --- /dev/null +++ b/packages/application/tests/session-service.test.ts @@ -0,0 +1,160 @@ +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}', + 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: '{}', + build: (ids) => ({ ...buildRevision(1)(ids), createdAt: 'yesterday' }), + }), + ).toThrow(RevisionInvalidError); +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9fd9cd2..12d6ec9 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -82,6 +82,9 @@ importers: '@archwise/domain': specifier: workspace:* version: link:../domain + '@archwise/schemas': + specifier: workspace:* + version: link:../schemas packages/domain: {} From 72019675aa36ee2d7ac7cbb3973c2df0ecfab59d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Oliveira?= Date: Sun, 15 Nov 2026 20:36:36 -0300 Subject: [PATCH 4/8] feat(storage): SQLite session store with migrations and recovery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Signed-off-by: André Oliveira --- .dependency-cruiser.mjs | 9 + packages/storage/README.md | 20 ++ packages/storage/package.json | 26 ++ packages/storage/src/data-dir.ts | 21 ++ packages/storage/src/index.ts | 3 + packages/storage/src/migrations.ts | 39 +++ packages/storage/src/sqlite-store.ts | 323 ++++++++++++++++++ packages/storage/tests/data-dir.test.ts | 28 ++ packages/storage/tests/helpers.ts | 8 + packages/storage/tests/lifecycle.test.ts | 187 ++++++++++ .../storage/tests/sqlite.contract.test.ts | 20 ++ packages/storage/tsconfig.check.json | 8 + packages/storage/tsconfig.json | 8 + packages/storage/vitest.config.ts | 2 + pnpm-lock.yaml | 12 + scripts/tests/boundaries.test.mjs | 16 + 16 files changed, 730 insertions(+) create mode 100644 packages/storage/README.md create mode 100644 packages/storage/package.json create mode 100644 packages/storage/src/data-dir.ts create mode 100644 packages/storage/src/index.ts create mode 100644 packages/storage/src/migrations.ts create mode 100644 packages/storage/src/sqlite-store.ts create mode 100644 packages/storage/tests/data-dir.test.ts create mode 100644 packages/storage/tests/helpers.ts create mode 100644 packages/storage/tests/lifecycle.test.ts create mode 100644 packages/storage/tests/sqlite.contract.test.ts create mode 100644 packages/storage/tsconfig.check.json create mode 100644 packages/storage/tsconfig.json create mode 100644 packages/storage/vitest.config.ts 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/packages/storage/README.md b/packages/storage/README.md new file mode 100644 index 0000000..2b50f62 --- /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; a corrupt file is 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 with a 5-second busy timeout, so two Archwise processes can share the file. +- 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..a5c9509 --- /dev/null +++ b/packages/storage/src/sqlite-store.ts @@ -0,0 +1,323 @@ +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 stampOf = (date: Date): string => date.toISOString().replace(/:/g, '-'); + +function isCorruption(error: unknown): boolean { + return ( + typeof error === 'object' && + error !== null && + 'errcode' in error && + CORRUPTION_CODES.has((error as { errcode: number }).errcode) + ); +} + +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; +} + +/** Opens and checks an existing file. Returns null when it is corrupt. */ +function openChecked(path: string): DatabaseSync | null { + let db: DatabaseSync | undefined; + try { + db = new DatabaseSync(path); + const rows = db.prepare('PRAGMA integrity_check').all() as { integrity_check: string }[]; + if (rows.length === 1 && rows[0]!.integrity_check === 'ok') return db; + db.close(); + return null; + } catch (error) { + db?.close(); + if (isCorruption(error)) return null; + throw error; + } +} + +function pruneBackups(dataDir: string): void { + const backups = readdirSync(dataDir) + .filter((name) => name.startsWith(`${DB_FILE}.backup-`)) + .sort(); + for (const name of backups.slice(0, Math.max(0, backups.length - KEPT_BACKUPS))) { + rmSync(join(dataDir, name), { force: true }); + } +} + +function migrate( + db: DatabaseSync, + from: number, + migrations: readonly Migration[], + now: Date, +): void { + const pending = migrations.filter((migration) => migration.version > from); + if (pending.length === 0) return; + try { + db.exec('BEGIN IMMEDIATE'); + 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 { + 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)) { + db = openChecked(path); + if (!db) { + quarantinedPath = `${path}.corrupt-${stampOf(now())}`; + renameSync(path, quarantinedPath); + } + } + db ??= new DatabaseSync(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, version, migrations, now()); + db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON'); + } catch (error) { + db.close(); + 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..faa8e48 --- /dev/null +++ b/packages/storage/tests/lifecycle.test.ts @@ -0,0 +1,187 @@ +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, 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(); + } +}); 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 12d6ec9..d9030e9 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -97,6 +97,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..a140fd9 100644 --- a/scripts/tests/boundaries.test.mjs +++ b/scripts/tests/boundaries.test.mjs @@ -90,3 +90,19 @@ 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); +}); From 2cc432fe0b5bf018988ca11820f9419088b13e59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Oliveira?= Date: Sun, 15 Nov 2026 20:37:33 -0300 Subject: [PATCH 5/8] feat(cli): map discovered package graph to archwise.graph revisions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Signed-off-by: André Oliveira --- apps/cli/package.json | 6 ++ apps/cli/src/revision.ts | 107 ++++++++++++++++++++++++++++++ apps/cli/tests/revision.test.ts | 113 ++++++++++++++++++++++++++++++++ pnpm-lock.yaml | 15 ++++- 4 files changed, 240 insertions(+), 1 deletion(-) create mode 100644 apps/cli/src/revision.ts create mode 100644 apps/cli/tests/revision.test.ts 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/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/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/pnpm-lock.yaml b/pnpm-lock.yaml index d9030e9..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: {} From 4589a5ce98bb41a390b2a45f5e1c730984dde2af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Oliveira?= Date: Sun, 15 Nov 2026 20:39:06 -0300 Subject: [PATCH 6/8] feat(cli): protected session API on the loopback server MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Signed-off-by: André Oliveira --- apps/cli/src/http.ts | 8 ++ apps/cli/src/local-server.ts | 27 ++-- apps/cli/src/session-routes.ts | 141 ++++++++++++++++++++ apps/cli/tests/session-api.test.ts | 201 +++++++++++++++++++++++++++++ 4 files changed, 367 insertions(+), 10 deletions(-) create mode 100644 apps/cli/src/http.ts create mode 100644 apps/cli/src/session-routes.ts create mode 100644 apps/cli/tests/session-api.test.ts 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/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/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/tests/session-api.test.ts b/apps/cli/tests/session-api.test.ts new file mode 100644 index 0000000..7dbfdba --- /dev/null +++ b/apps/cli/tests/session-api.test.ts @@ -0,0 +1,201 @@ +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), + 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); +}); From e7075451f2fd8b3aa18fcde808c4add9135795a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Oliveira?= Date: Sun, 15 Nov 2026 20:47:44 -0300 Subject: [PATCH 7/8] feat(cli): persist sessions locally with --sessions and --no-store MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Compose the SQLite store and SessionService in the CLI: - record each discovery as a revision; - serve the session API; - list sessions with --sessions; - opt out with --no-store. Store failures exit with code 2 and an actionable message. Corrupt files are quarantined. Docs: ADR 0006, the sessions guide, and updates to README, roadmap, architecture, security, alpha guide and package READMEs. Co-Authored-By: Claude Opus 5.5 Signed-off-by: André Oliveira --- .changeset/session-store.md | 7 + README.md | 4 +- apps/cli/README.md | 2 + apps/cli/src/bin.ts | 59 ++++++-- apps/cli/src/index.ts | 28 +++- apps/cli/src/store-runtime.ts | 94 ++++++++++++ apps/cli/tests/cli.test.ts | 16 ++ docs/alpha-testing.md | 2 +- docs/architecture.md | 10 +- docs/code-organization.md | 3 +- .../decisions/0006-local-store-node-sqlite.md | 38 +++++ docs/implementation-roadmap.md | 10 +- docs/security.md | 9 ++ docs/sessions.md | 73 ++++++++++ packages/application/README.md | 13 +- scripts/tests/boundaries.test.mjs | 3 +- .../tests/session-store-integration.test.mjs | 137 ++++++++++++++++++ 17 files changed, 482 insertions(+), 26 deletions(-) create mode 100644 .changeset/session-store.md create mode 100644 apps/cli/src/store-runtime.ts create mode 100644 docs/decisions/0006-local-store-node-sqlite.md create mode 100644 docs/sessions.md create mode 100644 scripts/tests/session-store-integration.test.mjs 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/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/src/bin.ts b/apps/cli/src/bin.ts index 70be8c9..41d4fa1 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' + ? 'Sandbox sessions are saved locally. List them with --sessions.\n' + : 'Sessions are not saved in 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/index.ts b/apps/cli/src/index.ts index 716da7b..d199338 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 saves\n' + + 'Sandbox sessions in the local store (outside the project); --no-store runs without saving.\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/store-runtime.ts b/apps/cli/src/store-runtime.ts new file mode 100644 index 0000000..9a887d0 --- /dev/null +++ b/apps/cli/src/store-runtime.ts @@ -0,0 +1,94 @@ +import { createHash, randomBytes } from 'node:crypto'; +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. + */ +export async function prepareStore(options: PrepareStoreOptions): Promise { + if (!options.enabled) return { kind: 'disabled', notices: [] }; + 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), + 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..bb53b96 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,17 @@ 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'); +}); 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..3aa8126 --- /dev/null +++ b/docs/sessions.md @@ -0,0 +1,73 @@ +# 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. +- **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 also require a same-origin `Origin` header and 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 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. | +| 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 not writable | It exits with code 2. Fix the permissions or set `ARCHWISE_DATA_DIR`. | + +Two Archwise processes can use the store at the same time. 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/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/scripts/tests/boundaries.test.mjs b/scripts/tests/boundaries.test.mjs index a140fd9..e5daf0a 100644 --- a/scripts/tests/boundaries.test.mjs +++ b/scripts/tests/boundaries.test.mjs @@ -102,7 +102,8 @@ test('rejects storage imports of app code', async () => { 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');", + '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 }); + } +}); From b3646e65fb8513ad185619cc7e572bc8506d3ef4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Oliveira?= Date: Sun, 15 Nov 2026 20:55:51 -0300 Subject: [PATCH 8/8] fix(storage,cli): harden session store from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Set busy_timeout on every connection before any work, and re-read the schema version under the write lock, so concurrent first opens succeed. - Probe integrity through a read-only connection so a corrupt file's WAL is quarantined intact instead of being deleted on close. - Prune backups by schema version, then time. - Report a read-only store file as unwritable (exit 2). - Include the view identity in the revision fingerprint so a changed view (e.g. framework labels) is never served from a stale revision. - Disable the store when its directory is inside the analyzed project. - CLI and docs no longer claim the Studio already saves sessions. Co-Authored-By: Claude Opus 5.5 Signed-off-by: André Oliveira --- apps/cli/src/bin.ts | 4 +- apps/cli/src/index.ts | 4 +- apps/cli/src/store-runtime.ts | 28 +++++ apps/cli/tests/cli.test.ts | 7 ++ apps/cli/tests/session-api.test.ts | 1 + apps/cli/tests/store-runtime.test.ts | 64 +++++++++++ docs/sessions.md | 52 ++++----- packages/application/src/session-service.ts | 16 ++- .../application/tests/session-service.test.ts | 24 +++++ packages/storage/README.md | 4 +- packages/storage/src/sqlite-store.ts | 101 ++++++++++++------ packages/storage/tests/lifecycle.test.ts | 85 ++++++++++++++- 12 files changed, 322 insertions(+), 68 deletions(-) create mode 100644 apps/cli/tests/store-runtime.test.ts diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts index 41d4fa1..9606a65 100644 --- a/apps/cli/src/bin.ts +++ b/apps/cli/src/bin.ts @@ -86,8 +86,8 @@ if (command.kind === 'output') { process.stdout.write(`Local session URL: ${server.bootstrapUrl}\n`); process.stdout.write( runtime.kind === 'ready' - ? 'Sandbox sessions are saved locally. List them with --sessions.\n' - : 'Sessions are not saved in this run.\n', + ? '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); diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts index d199338..96a1557 100644 --- a/apps/cli/src/index.ts +++ b/apps/cli/src/index.ts @@ -32,8 +32,8 @@ export function parseCli(args: readonly string[], version = 'development'): CliC stdout: '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 saves\n' + - 'Sandbox sessions in the local store (outside the project); --no-store runs without saving.\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: '', }, }; diff --git a/apps/cli/src/store-runtime.ts b/apps/cli/src/store-runtime.ts index 9a887d0..e50b865 100644 --- a/apps/cli/src/store-runtime.ts +++ b/apps/cli/src/store-runtime.ts @@ -1,4 +1,6 @@ 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'; @@ -25,8 +27,33 @@ export interface PrepareStoreOptions { * 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) { @@ -46,6 +73,7 @@ export async function prepareStore(options: PrepareStoreOptions): Promise buildGraphRevision(options.graph, options.rootLabel, ids), }, ); diff --git a/apps/cli/tests/cli.test.ts b/apps/cli/tests/cli.test.ts index bb53b96..bb0b3bb 100644 --- a/apps/cli/tests/cli.test.ts +++ b/apps/cli/tests/cli.test.ts @@ -59,3 +59,10 @@ test('lists saved sessions and controls the local store', () => { 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/session-api.test.ts b/apps/cli/tests/session-api.test.ts index 7dbfdba..6de2014 100644 --- a/apps/cli/tests/session-api.test.ts +++ b/apps/cli/tests/session-api.test.ts @@ -29,6 +29,7 @@ function service(): SessionService { { rootPath: '/secret/absolute/root', view: JSON.stringify(graph), + viewIdentity: JSON.stringify(graph), build: (ids) => buildGraphRevision(graph, 'root', ids), }, ); 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/sessions.md b/docs/sessions.md index 3aa8126..e689a48 100644 --- a/docs/sessions.md +++ b/docs/sessions.md @@ -6,15 +6,16 @@ Each time you launch the Studio on a project, Archwise starts a **fresh session* ## What is stored, and where -| Platform | Directory | -|---|---| -| macOS | `~/Library/Application Support/Archwise` | -| Linux | `$XDG_DATA_HOME/archwise`, or `~/.local/share/archwise` | -| Windows | `%LOCALAPPDATA%\Archwise` | +| 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. +- **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. @@ -28,6 +29,7 @@ node apps/cli/dist/bin.js --serve --no-store --path /absolute/path/to/project ``` Each line of `--sessions` shows, in order: + - when the session last changed; - its label (by default `Sandbox · N components`); - its component count; @@ -41,33 +43,35 @@ A session is saved only after its first Sandbox change. Launches where nothing c ## Session API (loopback, capability-protected) -The Studio will use these endpoints. All of them require the local session cookie. Mutations also require a same-origin `Origin` header and a JSON body. +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 | +| 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 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. | -| 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 not writable | It exits with code 2. Fix the permissions or set `ARCHWISE_DATA_DIR`. | +| 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. When both save the same session, the last write wins. +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/packages/application/src/session-service.ts b/packages/application/src/session-service.ts index 764e95e..39cc4f9 100644 --- a/packages/application/src/session-service.ts +++ b/packages/application/src/session-service.ts @@ -38,6 +38,11 @@ export interface RevisionIds { 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; } @@ -65,8 +70,11 @@ const fail = (error: ServiceError): { readonly ok: false; readonly error: Servic const defaultLabel = (count: number): string => `Sandbox · ${count} component${count === 1 ? '' : 's'}`; -/** Fingerprint of graph content, independent of revision identity, time and parent. */ -function fingerprint(revision: GraphRevision, digest: Digest): string { +/** + * 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', @@ -74,7 +82,7 @@ function fingerprint(revision: GraphRevision, digest: Digest): string { parentRevisionId: null, }); if (!serialized.ok) throw new RevisionInvalidError(serialized.issues); - return digest.sha256Hex(serialized.value); + return digest.sha256Hex(`${serialized.value}\n${viewIdentity}`); } /** @@ -107,7 +115,7 @@ export class SessionService { }), ); if (!created.ok) throw new RevisionInvalidError(created.issues); - const print = fingerprint(created.value, digest); + const print = fingerprint(created.value, discovery.viewIdentity, digest); let revisionId = created.value.id; if (latest && latest.fingerprint === print) { revisionId = latest.id; diff --git a/packages/application/tests/session-service.test.ts b/packages/application/tests/session-service.test.ts index 2ce873a..8528f1b 100644 --- a/packages/application/tests/session-service.test.ts +++ b/packages/application/tests/session-service.test.ts @@ -18,6 +18,7 @@ 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); @@ -154,7 +155,30 @@ test('an invalid discovered revision throws RevisionInvalidError', () => { 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 index 2b50f62..b71e7e6 100644 --- a/packages/storage/README.md +++ b/packages/storage/README.md @@ -8,11 +8,11 @@ Local SQLite store, built on Node's built-in `node:sqlite`. It implements the `@ - 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; a corrupt file is renamed to `archwise.db.corrupt-` and a fresh store starts; + 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 with a 5-second busy timeout, so two Archwise processes can share the file. + 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. diff --git a/packages/storage/src/sqlite-store.ts b/packages/storage/src/sqlite-store.ts index a5c9509..4bc6b81 100644 --- a/packages/storage/src/sqlite-store.ts +++ b/packages/storage/src/sqlite-store.ts @@ -47,17 +47,26 @@ export interface OpenStoreOptions { 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, '-'); -function isCorruption(error: unknown): boolean { - return ( - typeof error === 'object' && - error !== null && - 'errcode' in error && - CORRUPTION_CODES.has((error as { errcode: number }).errcode) - ); -} +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 { @@ -80,41 +89,60 @@ function schemaVersion(db: DatabaseSync): number { return row.version ?? 0; } -/** Opens and checks an existing file. Returns null when it is corrupt. */ +/** + * 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 db: DatabaseSync | undefined; + let probe: DatabaseSync | undefined; try { - db = new DatabaseSync(path); - const rows = db.prepare('PRAGMA integrity_check').all() as { integrity_check: string }[]; - if (rows.length === 1 && rows[0]!.integrity_check === 'ok') return db; - db.close(); - return null; + 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) { - db?.close(); if (isCorruption(error)) return null; throw error; + } finally { + probe?.close(); } + return connect(path); } -function pruneBackups(dataDir: string): void { +/** Keeps the newest backups, ordered by schema version and then by timestamp. */ +export function pruneBackups(dataDir: string): void { const backups = readdirSync(dataDir) - .filter((name) => name.startsWith(`${DB_FILE}.backup-`)) - .sort(); - for (const name of backups.slice(0, Math.max(0, backups.length - KEPT_BACKUPS))) { + .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 }); } } -function migrate( - db: DatabaseSync, - from: number, - migrations: readonly Migration[], - now: Date, -): void { - const pending = migrations.filter((migration) => migration.version > from); - if (pending.length === 0) return; +/** 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)', ); @@ -126,7 +154,8 @@ function migrate( ); } db.exec('COMMIT'); - } catch { + } catch (error) { + if (errcodeOf(error) === READONLY_CODE) throw new StoreUnavailableError('unwritable'); try { db.exec('ROLLBACK'); } catch { @@ -155,13 +184,18 @@ export async function openStore( 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())}`; - renameSync(path, quarantinedPath); + quarantine(path, quarantinedPath); } } - db ??= new DatabaseSync(path); + db ??= connect(path); let backupPath: string | null = null; try { @@ -172,10 +206,11 @@ export async function openStore( await backup(db, backupPath); pruneBackups(dataDir); } - migrate(db, version, migrations, now()); - db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON'); + 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); diff --git a/packages/storage/tests/lifecycle.test.ts b/packages/storage/tests/lifecycle.test.ts index faa8e48..32f4ebd 100644 --- a/packages/storage/tests/lifecycle.test.ts +++ b/packages/storage/tests/lifecycle.test.ts @@ -9,7 +9,7 @@ import { import { join } from 'node:path'; import { DatabaseSync } from 'node:sqlite'; import { afterEach, expect, test } from 'vitest'; -import { openStore, SCHEMA_VERSION, StoreUnavailableError } from '../src/index.js'; +import { openStore, pruneBackups, SCHEMA_VERSION, StoreUnavailableError } from '../src/index.js'; import { tempDir } from './helpers.js'; const cleanups: (() => void)[] = []; @@ -185,3 +185,86 @@ test('two handles on the same file can interleave writes', async () => { 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'); + }, +);