Files

glm-5.1 bb544469fd 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).

2026-05-28 13:38:42 +00:00

5.0 KiB

Raw Blame History

AGENTS.md — @alkdev/storage

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.

Architecture Snapshot

@alkdev/storage/
├── mod.ts                   # Re-exports graphs/ only (zero db deps)
├── deno.json                # JSR config, imports, tasks, lint rules
├── src/
│   ├── graphs/              # Schema types + SchemaBuilder (no db deps)
│   ├── sqlite/              # SQLite host (drizzle-orm/libsql)
│   │   ├── tables/          # Drizzle table definitions
│   │   ├── relations.ts     # Drizzle relations
│   │   ├── schema.ts        # Re-exports
│   │   └── client.ts        # Injectable createSqliteDatabase()
│   └── pg/                  # PostgreSQL host (NOT YET IMPLEMENTED)
└── test/

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)

This design ensures consumers don't bundle database drivers they don't use.

Key Decisions

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.
No comments in code: Per project convention across @alkdev packages.
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.
Injectable clients: createSqliteDatabase(client) takes a client, not env vars. Module-level side effects are forbidden.
Dependencies: @alkdev/typebox and @alkdev/drizzlebox are npm deps (not yet on JSR). This works fine — JSR handles npm dependencies natively.

Commands

deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts  # Type check
deno lint                                               # Lint (slow-types, verbatim-module-syntax excluded)
deno task lint:analyze                                  # Analyze lint issues by code/file grouping
deno fmt                                                # Format
deno test --allow-all test/                             # Run tests
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:

@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)
Relation type alias removed (JSR slow type)
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)
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)

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
sqlite-host.md — SQLite tables, relations, client factory, porting notes
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.

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)
Tests
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)

5.0 KiB Raw Blame History