fix: use import type for GraphConfig, remove verbatim-module-syntax exclusion

The verbatim-module-syntax lint rule was correctly flagging that
GraphConfig is only used in a type position (typeof GraphConfig). Since
typeof resolves purely at the type level, import type works fine here
and is the correct form. No lint exclusion needed.

Also: deno fmt across all files (markdown line wrapping).
This commit is contained in:
2026-05-28 13:38:42 +00:00
parent b0298663dc
commit bb544469fd
34 changed files with 1279 additions and 617 deletions

View File

@@ -4,7 +4,10 @@ Project-specific guidance for agents working on this package.
## Project Overview
`@alkdev/storage` is a deno-first TypeScript package providing typed graph storage with dual database hosts (SQLite for spokes, PostgreSQL for the hub). It uses the metagraph pattern (graphTypes → nodeTypes → edgeTypes → typed graph instances) from the earlier `@ade` prototype.
`@alkdev/storage` is a deno-first TypeScript package providing typed graph
storage with dual database hosts (SQLite for spokes, PostgreSQL for the hub). It
uses the metagraph pattern (graphTypes → nodeTypes → edgeTypes → typed graph
instances) from the earlier `@ade` prototype.
## Architecture Snapshot
@@ -26,18 +29,28 @@ Project-specific guidance for agents working on this package.
### Subpath Exports (JSR/npm)
- `@alkdev/storage` → graphs types + SchemaBuilder (zero deps)
- `@alkdev/storage/sqlite` → SQLite tables, relations, client (drizzle-orm + libsql)
- `@alkdev/storage/pg` → PostgreSQL tables, relations, client (NOT YET IMPLEMENTED)
- `@alkdev/storage/sqlite` → SQLite tables, relations, client (drizzle-orm +
libsql)
- `@alkdev/storage/pg` → PostgreSQL tables, relations, client (NOT YET
IMPLEMENTED)
This design ensures consumers don't bundle database drivers they don't use.
## Key Decisions
1. **Deno-first, npm-second via JSR**: Package is published to JSR (`deno publish`). npm compatibility is automatic via JSR's npm layer (`@jsr/alkdev__storage`). No separate dnt build step.
1. **Deno-first, npm-second via JSR**: Package is published to JSR
(`deno publish`). npm compatibility is automatic via JSR's npm layer
(`@jsr/alkdev__storage`). No separate dnt build step.
2. **No comments in code**: Per project convention across @alkdev packages.
3. **JSR slow types excluded from lint**: Drizzle's deeply inferred generics (`sqliteTable`, `createInsertSchema`, `relations`) make explicit type annotations impractical. We use `--allow-slow-types` on publish and `"exclude": ["no-slow-types"]` in lint config. Additionally, `"verbatim-module-syntax"` is excluded because TypeBox schemas are runtime values used as `typeof` type references, which the linter misidentifies as type-only imports. This is known technical debt — can be tightened iteratively.
4. **Injectable clients**: `createSqliteDatabase(client)` takes a client, not env vars. Module-level side effects are forbidden.
5. **Dependencies**: `@alkdev/typebox` and `@alkdev/drizzlebox` are npm deps (not yet on JSR). This works fine — JSR handles npm dependencies natively.
3. **JSR slow types excluded from lint**: Drizzle's deeply inferred generics
(`sqliteTable`, `createInsertSchema`, `relations`) make explicit type
annotations impractical. We use `--allow-slow-types` on publish and
`"exclude": ["no-slow-types"]` in lint config. This is known technical debt —
can be tightened iteratively.
4. **Injectable clients**: `createSqliteDatabase(client)` takes a client, not
env vars. Module-level side effects are forbidden.
5. **Dependencies**: `@alkdev/typebox` and `@alkdev/drizzlebox` are npm deps
(not yet on JSR). This works fine — JSR handles npm dependencies natively.
## Commands
@@ -52,42 +65,55 @@ deno publish --allow-slow-types --dry-run # Dry-run publish
## Source Heritage
The `graphs/` and `sqlite/` modules were adapted from `@ade/ade-v0/packages/core/graphs` and `@ade/ade-v0/packages/storage_sqlite`. Key changes from the originals:
The `graphs/` and `sqlite/` modules were adapted from
`@ade/ade-v0/packages/core/graphs` and `@ade/ade-v0/packages/storage_sqlite`.
Key changes from the originals:
- `@sinclair/typebox``@alkdev/typebox`
- `drizzle-typebox``@alkdev/drizzlebox`
- `@ade/core` imports → relative imports within `src/graphs/`
- `import type { GraphConfig }``import { GraphConfig }` (TypeBox schemas are both values and types)
- `import type { GraphConfig }``import { GraphConfig }` (TypeBox schemas are
both values and types)
- `Relation` type alias removed (JSR slow type)
- TypeScript enums replaced with `as const` objects (`EnumGraphStatus` `GRAPH_STATUS`)
- TypeScript enums replaced with `as const` objects (`EnumGraphStatus`
`GRAPH_STATUS`)
- `client.ts` refactored to be injectable
- Module-level `db` and `client` exports removed
## File Conventions
- All source files use `.ts` extension with explicit extensions in imports (Deno convention)
- All source files use `.ts` extension with explicit extensions in imports (Deno
convention)
- Entry points are `mod.ts` files that re-export from subdirectories
- TypeBox schemas are named with PascalCase (`NodeType`, `GraphConfig`)
- Drizzle table objects are named with camelCase (`graphTypes`, `nodeTypes`)
- Schema objects from drizzlebox are named with PascalCase (`InsertGraph`, `SelectGraph`)
- Enum constants use `SCREAMING_SNAKE_CASE` objects (`GRAPH_STATUS`, `ACTOR_TYPE`)
- Schema objects from drizzlebox are named with PascalCase (`InsertGraph`,
`SelectGraph`)
- Enum constants use `SCREAMING_SNAKE_CASE` objects (`GRAPH_STATUS`,
`ACTOR_TYPE`)
## Architecture Docs
See `docs/architecture/` for detailed specifications:
- `overview.md` — Package purpose, exports, design decisions, open questions
- `metagraph.md` — Core graph model, schema types, SchemaBuilder, attribute storage
- `metagraph.md` — Core graph model, schema types, SchemaBuilder, attribute
storage
- `sqlite-host.md` — SQLite tables, relations, client factory, porting notes
- `encrypted-data.md` — Encrypted data design (planned), crypto utility, node type modeling
- `encrypted-data.md` — Encrypted data design (planned), crypto utility, node
type modeling
These docs describe what the package is AND what it's becoming. Items marked ⚠️ are not yet implemented.
These docs describe what the package is AND what it's becoming. Items marked ⚠️
are not yet implemented.
## What's Not Done Yet
- `src/pg/` — PostgreSQL host (same table shapes, `pgTable` + `jsonb` + `timestamp` + `pgEnum`)
- `src/graphs/crypto.ts` — Crypto utility (`encrypt`, `decrypt`, `generateEncryptionKey`, `EncryptedDataSchema`)
- `src/pg/` — PostgreSQL host (same table shapes, `pgTable` + `jsonb` +
`timestamp` + `pgEnum`)
- `src/graphs/crypto.ts` — Crypto utility (`encrypt`, `decrypt`,
`generateEncryptionKey`, `EncryptedDataSchema`)
- Tests
- Repository/CRUD layer (currently only table definitions, no typed query functions)
- Repository/CRUD layer (currently only table definitions, no typed query
functions)
- Hub-specific tables (sessions, messages, parts, call graphs, tasks, etc.)
- JSR publication setup (need to create scope/package on jsr.io first)
- JSR publication setup (need to create scope/package on jsr.io first)