mirror of
https://github.com/kennethnym/aris.git
synced 2026-03-20 00:51:20 +00:00
feat: add actions to FeedSource interface
Add listActions() and executeAction() to FeedSource for write operations back to external services. Actions use arktype schemas for input validation via StandardSchemaV1. - ActionDefinition type with optional input schema - FeedEngine routes actions with existence and ID validation - Source IDs use reverse-domain format (aris.location, aris.tfl) - LocationSource: update-location action with schema validation - TflSource: set-lines-of-interest action with lineId validation - No-op implementations for sources without actions Co-authored-by: Ona <no-reply@ona.com>
This commit is contained in:
306
docs/backend-service-architecture-spec.md
Normal file
306
docs/backend-service-architecture-spec.md
Normal file
@@ -0,0 +1,306 @@
|
||||
# Backend Service Architecture: Per-User Refactor
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The current backend uses a **per-source service** pattern: each source type (Location, Weather, TFL) has its own `XxxService` class that manages a `Map<userId, SourceInstance>`. Adding a new source requires:
|
||||
|
||||
1. A new `XxxService` class with identical boilerplate (~30-40 lines: Map, get-or-create, removeUser)
|
||||
2. Wiring it into `server.ts` constructor
|
||||
3. Passing it to `FeedEngineService`
|
||||
4. Optionally adding source-specific tRPC routes
|
||||
|
||||
With 3 sources this is manageable. With 10+ (calendar, music, transit, news, etc.) it becomes:
|
||||
|
||||
- **Repetitive**: Every service class repeats the same Map + get-or-create + removeUser pattern
|
||||
- **Fragmented lifecycle**: User cleanup requires calling `removeUser` on every service independently
|
||||
- **No user-level config**: No unified place to store which sources a user has enabled or their per-source settings
|
||||
- **Hard to reason about**: User state is scattered across N independent Maps
|
||||
|
||||
### Current Flow
|
||||
|
||||
```
|
||||
server.ts
|
||||
├── new LocationService() ← owns Map<userId, LocationSource>
|
||||
├── new WeatherService(creds) ← owns Map<userId, WeatherSource>
|
||||
├── new TflService(api) ← owns Map<userId, TflSource>
|
||||
└── FeedEngineService([loc, weather, tfl])
|
||||
└── owns Map<userId, FeedEngine>
|
||||
└── on create: asks each service for feedSourceForUser(userId)
|
||||
```
|
||||
|
||||
4 independent Maps for 3 sources. Each user's state lives in 4 different places.
|
||||
|
||||
## Scope
|
||||
|
||||
**Backend only** (`apps/aris-backend`). No changes to `aris-core` or source packages (`packages/aris-source-*`). The `FeedSource` interface and source implementations remain unchanged.
|
||||
|
||||
## Architectural Options
|
||||
|
||||
### Option A: UserSession Object
|
||||
|
||||
A single `UserSession` class owns everything for one user. A `UserSessionManager` is the only top-level Map.
|
||||
|
||||
```typescript
|
||||
class UserSession {
|
||||
readonly userId: string
|
||||
readonly engine: FeedEngine
|
||||
private sources: Map<string, FeedSource>
|
||||
|
||||
constructor(userId: string, sourceFactories: SourceFactory[]) {
|
||||
this.engine = new FeedEngine()
|
||||
this.sources = new Map()
|
||||
for (const factory of sourceFactories) {
|
||||
const source = factory.create()
|
||||
this.sources.set(source.id, source)
|
||||
this.engine.register(source)
|
||||
}
|
||||
this.engine.start()
|
||||
}
|
||||
|
||||
getSource<T extends FeedSource>(id: string): T | undefined {
|
||||
return this.sources.get(id) as T | undefined
|
||||
}
|
||||
|
||||
destroy(): void {
|
||||
this.engine.stop()
|
||||
this.sources.clear()
|
||||
}
|
||||
}
|
||||
|
||||
class UserSessionManager {
|
||||
private sessions = new Map<string, UserSession>()
|
||||
|
||||
getOrCreate(userId: string): UserSession { ... }
|
||||
remove(userId: string): void { ... } // single cleanup point
|
||||
}
|
||||
```
|
||||
|
||||
**Source-specific operations** use typed accessors:
|
||||
|
||||
```typescript
|
||||
const session = manager.getOrCreate(userId)
|
||||
const location = session.getSource<LocationSource>("location")
|
||||
location?.pushLocation({ lat: 51.5, lng: -0.1, ... })
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Single Map, single cleanup point
|
||||
- All user state co-located
|
||||
- Easy to add TTL/eviction at one level
|
||||
- Source factories are simple functions, no service classes needed
|
||||
|
||||
**Cons:**
|
||||
|
||||
- `getSource<T>("id")` requires callers to know the source ID string and cast type
|
||||
- Shared resources (e.g., TFL API client) need to be passed through factories
|
||||
|
||||
### Option B: Source Registry with Factories
|
||||
|
||||
Keep `FeedEngineService` but replace per-source service classes with a registry of factory functions. No `XxxService` classes at all.
|
||||
|
||||
```typescript
|
||||
interface SourceFactory {
|
||||
readonly sourceId: string
|
||||
create(userId: string): FeedSource
|
||||
}
|
||||
|
||||
// Weather factory — closure over shared credentials
|
||||
function weatherSourceFactory(creds: WeatherKitCredentials): SourceFactory {
|
||||
return {
|
||||
sourceId: "weather",
|
||||
create: () => new WeatherSource({ credentials: creds }),
|
||||
}
|
||||
}
|
||||
|
||||
// TFL factory — closure over shared API client
|
||||
function tflSourceFactory(api: ITflApi): SourceFactory {
|
||||
return {
|
||||
sourceId: "tfl",
|
||||
create: () => new TflSource({ client: api }),
|
||||
}
|
||||
}
|
||||
|
||||
class FeedEngineService {
|
||||
private engines = new Map<string, FeedEngine>()
|
||||
private userSources = new Map<string, Map<string, FeedSource>>()
|
||||
|
||||
constructor(private readonly factories: SourceFactory[]) {}
|
||||
|
||||
engineForUser(userId: string): FeedEngine { ... }
|
||||
getSourceForUser<T extends FeedSource>(userId: string, sourceId: string): T | undefined { ... }
|
||||
removeUser(userId: string): void { ... } // cleans up engine + all sources
|
||||
}
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Minimal change from current structure — `FeedEngineService` evolves, services disappear
|
||||
- Factory functions are 5-10 lines each, no classes
|
||||
- Shared resources handled naturally via closures
|
||||
|
||||
**Cons:**
|
||||
|
||||
- `FeedEngineService` grows in responsibility (engine + source tracking + source access)
|
||||
- Still two Maps (engines + userSources), though co-located
|
||||
|
||||
### Option C: UserSession + Typed Source Handles (Recommended)
|
||||
|
||||
Combines Option A's co-location with type-safe source access. `UserSession` owns everything. Source-specific operations go through **source handles** — thin typed wrappers registered at setup time.
|
||||
|
||||
```typescript
|
||||
// Source handle: typed wrapper for source-specific operations
|
||||
interface SourceHandle<T extends FeedSource = FeedSource> {
|
||||
readonly source: T
|
||||
}
|
||||
|
||||
class UserSession {
|
||||
readonly engine: FeedEngine
|
||||
private handles = new Map<string, SourceHandle>()
|
||||
|
||||
register<T extends FeedSource>(source: T): SourceHandle<T> {
|
||||
this.engine.register(source)
|
||||
const handle: SourceHandle<T> = { source }
|
||||
this.handles.set(source.id, handle)
|
||||
return handle
|
||||
}
|
||||
|
||||
destroy(): void {
|
||||
this.engine.stop()
|
||||
this.handles.clear()
|
||||
}
|
||||
}
|
||||
|
||||
// In setup code — handles are typed at creation time
|
||||
function createSession(userId: string, deps: SessionDeps): UserSession {
|
||||
const session = new UserSession(userId)
|
||||
|
||||
const locationHandle = session.register(new LocationSource())
|
||||
const weatherHandle = session.register(new WeatherSource(deps.weatherCreds))
|
||||
const tflHandle = session.register(new TflSource({ client: deps.tflApi }))
|
||||
|
||||
return session
|
||||
}
|
||||
```
|
||||
|
||||
**Source-specific operations** use the typed handles returned at registration:
|
||||
|
||||
```typescript
|
||||
// In the tRPC router or wherever source-specific ops happen:
|
||||
// The handle is obtained during session setup and stored where needed
|
||||
locationHandle.source.pushLocation({ ... })
|
||||
tflHandle.source.setLinesOfInterest(["northern"])
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Single Map, single cleanup
|
||||
- Type-safe source access without string-based lookups or casts
|
||||
- No boilerplate service classes
|
||||
- Handles can be extended later (e.g., add per-source config, metrics)
|
||||
- Shared resources passed directly to constructors
|
||||
|
||||
**Cons:**
|
||||
|
||||
- Handles need to be threaded to where they're used (tRPC routers, etc.)
|
||||
- Slightly more setup code in the factory function
|
||||
|
||||
## Source-Specific Operations: Approaches
|
||||
|
||||
Orthogonal to the session model, there are three ways to handle operations like `pushLocation` or `setLinesOfInterest`:
|
||||
|
||||
### Approach 1: Direct Source Access (Recommended)
|
||||
|
||||
Callers get a typed reference to the source and call methods directly. This is what all three options above use in different ways.
|
||||
|
||||
```typescript
|
||||
locationSource.pushLocation(location)
|
||||
tflSource.setLinesOfInterest(lines)
|
||||
```
|
||||
|
||||
**Why this works:** Source packages already define these methods. The backend just needs to expose the source instance to the right caller. No new abstraction needed.
|
||||
|
||||
### Approach 2: Command Dispatch
|
||||
|
||||
A generic `dispatch(command)` method on the session routes typed commands to sources.
|
||||
|
||||
```typescript
|
||||
session.dispatch({ type: "location.update", payload: { lat: 51.5, ... } })
|
||||
```
|
||||
|
||||
**Tradeoff:** Adds indirection and a command type registry. Useful if sources are dynamically loaded plugins, but over-engineered for the current case where sources are known at compile time.
|
||||
|
||||
### Approach 3: Context-Only
|
||||
|
||||
All input goes through `FeedEngine` context updates. Sources react to context changes.
|
||||
|
||||
```typescript
|
||||
engine.pushContext({ [LocationKey]: location })
|
||||
// LocationSource picks this up via onContextUpdate
|
||||
```
|
||||
|
||||
**Tradeoff:** Location already works this way (it's a context provider). But not all operations map to context — `setLinesOfInterest` is configuration, not context. Would require stretching the context concept.
|
||||
|
||||
## User Source Configuration (DB-Persisted)
|
||||
|
||||
Regardless of which option is chosen, user source config needs a storage model:
|
||||
|
||||
```sql
|
||||
CREATE TABLE user_source_config (
|
||||
user_id TEXT NOT NULL REFERENCES users(id),
|
||||
source_id TEXT NOT NULL, -- e.g., "weather", "tfl", "location"
|
||||
enabled BOOLEAN NOT NULL DEFAULT true,
|
||||
config JSONB NOT NULL DEFAULT '{}', -- source-specific settings
|
||||
PRIMARY KEY (user_id, source_id)
|
||||
);
|
||||
```
|
||||
|
||||
On session creation:
|
||||
|
||||
1. Load `user_source_config` rows for the user
|
||||
2. Only create sources where `enabled = true`
|
||||
3. Pass `config` JSON to the source factory/constructor
|
||||
|
||||
New users get default config rows inserted on first login.
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Option C (UserSession + Typed Source Handles)** with **Approach 1 (Direct Source Access)**.
|
||||
|
||||
Rationale:
|
||||
|
||||
- Eliminates all per-source service boilerplate
|
||||
- Single user lifecycle management point
|
||||
- Type-safe without string-based lookups in hot paths
|
||||
- Minimal new abstraction — `UserSession` is a thin container, not a framework
|
||||
- Handles are just typed references, not a new pattern to learn
|
||||
- Natural extension point for per-user config loading from DB
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **No per-source service classes**: `LocationService`, `WeatherService`, `TflService` are removed
|
||||
2. **Single user state container**: All per-user state (engine, sources) lives in one object
|
||||
3. **Single cleanup**: Removing a user requires one call, not N
|
||||
4. **Type-safe source access**: Source-specific operations don't require string-based lookups or unsafe casts at call sites
|
||||
5. **Existing tests pass**: `FeedEngineService` tests are migrated to the new structure
|
||||
6. **tRPC routes work**: Location update route works through the new architecture
|
||||
7. **DB config table**: `user_source_config` table exists; session creation reads from it
|
||||
8. **Default config**: New users get default source config on first session
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Create `user_source_config` DB table and migration
|
||||
2. Create `UserSession` class with `register()`, `destroy()`, typed handle return
|
||||
3. Create `UserSessionManager` with `getOrCreate()`, `remove()`, config loading
|
||||
4. Create `createSession()` factory that reads DB config and registers enabled sources
|
||||
5. Refactor `server.ts` to use `UserSessionManager` instead of individual services
|
||||
6. Refactor tRPC router to receive session/handles instead of individual services
|
||||
7. Delete `LocationService`, `WeatherService`, `TflService` classes
|
||||
8. Migrate existing tests to new structure
|
||||
9. Add tests for session lifecycle (create, destroy, config loading)
|
||||
|
||||
## Open Questions
|
||||
|
||||
- **TTL/eviction**: Should `UserSessionManager` handle idle session cleanup? (Currently deferred in backend-spec.md)
|
||||
- **Hot reload config**: If a user changes their source config, should the session be recreated or patched in-place?
|
||||
- **Shared source instances**: Some sources (e.g., TFL) share an API client. Should the factory receive shared deps, or should there be a DI container?
|
||||
269
docs/feed-source-actions-spec.md
Normal file
269
docs/feed-source-actions-spec.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# FeedSource Actions
|
||||
|
||||
## Problem Statement
|
||||
|
||||
`FeedSource` is read-only. Sources can provide context and feed items but can't expose write operations (play, RSVP, dismiss). This blocks interactive sources like Spotify, calendar, and tasks.
|
||||
|
||||
## Scope
|
||||
|
||||
**`aris-core` only.** Add action support to `FeedSource` and `FeedItem`. No changes to existing fields or methods — purely additive.
|
||||
|
||||
## Design
|
||||
|
||||
### Why Not MCP
|
||||
|
||||
MCP was considered. It doesn't fit because:
|
||||
|
||||
- MCP resources don't accept input context (FeedSource needs accumulated context as input)
|
||||
- MCP has no structured feed items (priority, timestamp, type)
|
||||
- MCP's isolation model conflicts with ARIS's dependency graph
|
||||
- Adding these as MCP extensions would mean the extensions are the entire protocol
|
||||
|
||||
The interface is designed to be **protocol-compatible** — a future `RemoteFeedSource` adapter can map each field/method to a JSON-RPC operation without changing the interface:
|
||||
|
||||
| FeedSource field/method | Future protocol operation |
|
||||
| ----------------------- | ------------------------- |
|
||||
| `id`, `dependencies` | `source/describe` |
|
||||
| `listActions()` | `source/listActions` |
|
||||
| `fetchContext()` | `source/fetchContext` |
|
||||
| `fetchItems()` | `source/fetchItems` |
|
||||
| `executeAction()` | `source/executeAction` |
|
||||
| `onContextUpdate()` | `source/contextUpdated` |
|
||||
| `onItemsUpdate()` | `source/itemsUpdated` |
|
||||
|
||||
No interface changes needed when the transport layer is built.
|
||||
|
||||
### Source ID & Action ID Convention
|
||||
|
||||
Source IDs use reverse domain notation. Built-in sources use `aris.<name>`. Third parties use their own domain.
|
||||
|
||||
Action IDs are descriptive verb-noun pairs in kebab-case, scoped to their source. The globally unique form is `<sourceId>/<actionId>`.
|
||||
|
||||
| Source ID | Action IDs |
|
||||
| --------------- | -------------------------------------------------------------- |
|
||||
| `aris.location` | `update-location` (migrated from `pushLocation()`) |
|
||||
| `aris.tfl` | `set-lines-of-interest` (migrated from `setLinesOfInterest()`) |
|
||||
| `aris.weather` | _(none)_ |
|
||||
| `com.spotify` | `play-track`, `pause-playback`, `skip-track`, `like-track` |
|
||||
| `aris.calendar` | `rsvp`, `create-event` |
|
||||
| `com.todoist` | `complete-task`, `snooze-task` |
|
||||
|
||||
This means existing source packages need their `id` updated (e.g., `"location"` → `"aris.location"`).
|
||||
|
||||
### New Types
|
||||
|
||||
```typescript
|
||||
/** Describes an action a source can perform. */
|
||||
interface ActionDefinition<TInput = unknown> {
|
||||
/** Descriptive action name in kebab-case (e.g., "update-location", "play-track") */
|
||||
readonly id: string
|
||||
/** Human-readable label for UI (e.g., "Play", "RSVP Yes") */
|
||||
readonly label: string
|
||||
/** Optional longer description */
|
||||
readonly description?: string
|
||||
/** Schema for input validation. Accepts any Standard Schema compatible validator (arktype, zod, valibot, etc.). Omit if no params. */
|
||||
readonly input?: StandardSchemaV1<TInput>
|
||||
}
|
||||
```
|
||||
|
||||
`StandardSchemaV1` is the [Standard Schema](https://github.com/standard-schema/standard-schema) interface implemented by arktype, zod, and valibot. This means sources can use any validator:
|
||||
|
||||
```typescript
|
||||
import { type } from "arktype"
|
||||
import { z } from "zod"
|
||||
|
||||
// With arktype
|
||||
{ id: "play-track", label: "Play", input: type({ trackId: "string" }) }
|
||||
|
||||
// With zod
|
||||
{ id: "play-track", label: "Play", input: z.object({ trackId: z.string() }) }
|
||||
|
||||
// Without validation (e.g., remote sources using raw JSON Schema)
|
||||
{ id: "play-track", label: "Play" }
|
||||
|
||||
/** Result of executing an action. */
|
||||
interface ActionResult {
|
||||
ok: boolean
|
||||
data?: Record<string, unknown>
|
||||
error?: string
|
||||
}
|
||||
|
||||
/** Reference to an action on a specific feed item. */
|
||||
interface ItemAction {
|
||||
/** Action ID (matches ActionDefinition.id on the source) */
|
||||
actionId: string
|
||||
/** Per-item label override (e.g., "RSVP to standup") */
|
||||
label?: string
|
||||
/** Pre-filled params for this item (e.g., { eventId: "abc" }) */
|
||||
params?: Record<string, unknown>
|
||||
}
|
||||
```
|
||||
|
||||
### Changes to FeedSource
|
||||
|
||||
Two optional fields added. Nothing else changes.
|
||||
|
||||
```typescript
|
||||
interface FeedSource<TItem extends FeedItem = FeedItem> {
|
||||
readonly id: string // unchanged
|
||||
readonly dependencies?: readonly string[] // unchanged
|
||||
fetchContext(...): ... // unchanged
|
||||
onContextUpdate?(...): ... // unchanged
|
||||
fetchItems?(...): ... // unchanged
|
||||
onItemsUpdate?(...): ... // unchanged
|
||||
|
||||
/** List actions this source supports. Empty record if none. Maps to: source/listActions */
|
||||
listActions(): Promise<Record<string, ActionDefinition>>
|
||||
|
||||
/** Execute an action by ID. No-op returning { ok: false } if source has no actions. */
|
||||
executeAction(
|
||||
actionId: string,
|
||||
params: Record<string, unknown>,
|
||||
): Promise<ActionResult>
|
||||
}
|
||||
```
|
||||
|
||||
### Changes to FeedItem
|
||||
|
||||
One optional field added.
|
||||
|
||||
```typescript
|
||||
interface FeedItem<
|
||||
TType extends string = string,
|
||||
TData extends Record<string, unknown> = Record<string, unknown>,
|
||||
> {
|
||||
id: string // unchanged
|
||||
type: TType // unchanged
|
||||
priority: number // unchanged
|
||||
timestamp: Date // unchanged
|
||||
data: TData // unchanged
|
||||
|
||||
/** Actions the user can take on this item. */
|
||||
actions?: readonly ItemAction[]
|
||||
}
|
||||
```
|
||||
|
||||
### Changes to FeedEngine
|
||||
|
||||
Two new methods. Existing methods unchanged.
|
||||
|
||||
```typescript
|
||||
class FeedEngine {
|
||||
// All existing methods unchanged...
|
||||
|
||||
/** Route an action call to the correct source. */
|
||||
async executeAction(
|
||||
sourceId: string,
|
||||
actionId: string,
|
||||
params: Record<string, unknown>,
|
||||
): Promise<ActionResult>
|
||||
|
||||
/** List all actions across all registered sources. */
|
||||
listActions(): { sourceId: string; actions: readonly ActionDefinition[] }[]
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Spotify Source
|
||||
|
||||
```typescript
|
||||
class SpotifySource implements FeedSource<SpotifyFeedItem> {
|
||||
readonly id = "com.spotify"
|
||||
|
||||
async listActions() {
|
||||
return {
|
||||
"play-track": { id: "play-track", label: "Play", input: type({ trackId: "string" }) },
|
||||
"pause-playback": { id: "pause-playback", label: "Pause" },
|
||||
"skip-track": { id: "skip-track", label: "Skip" },
|
||||
"like-track": { id: "like-track", label: "Like", input: type({ trackId: "string" }) },
|
||||
}
|
||||
}
|
||||
|
||||
async executeAction(actionId: string, params: Record<string, unknown>): Promise<ActionResult> {
|
||||
switch (actionId) {
|
||||
case "play-track":
|
||||
await this.client.play(params.trackId as string)
|
||||
return { ok: true }
|
||||
case "pause-playback":
|
||||
await this.client.pause()
|
||||
return { ok: true }
|
||||
case "skip-track":
|
||||
await this.client.skip()
|
||||
return { ok: true }
|
||||
case "like-track":
|
||||
await this.client.like(params.trackId as string)
|
||||
return { ok: true }
|
||||
default:
|
||||
return { ok: false, error: `Unknown action: ${actionId}` }
|
||||
}
|
||||
}
|
||||
|
||||
async fetchContext(): Promise<null> {
|
||||
return null
|
||||
}
|
||||
|
||||
// Note: for a source with no actions, it would be:
|
||||
// async listActions() { return {} }
|
||||
// async executeAction(): Promise<ActionResult> {
|
||||
// return { ok: false, error: "No actions supported" }
|
||||
// }
|
||||
|
||||
async fetchItems(context: Context): Promise<SpotifyFeedItem[]> {
|
||||
const track = await this.client.getCurrentTrack()
|
||||
if (!track) return []
|
||||
return [
|
||||
{
|
||||
id: `spotify-${track.id}`,
|
||||
type: "spotify-now-playing",
|
||||
priority: 0.4,
|
||||
timestamp: context.time,
|
||||
data: { trackName: track.name, artist: track.artist },
|
||||
actions: [
|
||||
{ actionId: "pause-playback" },
|
||||
{ actionId: "skip-track" },
|
||||
{ actionId: "like-track", params: { trackId: track.id } },
|
||||
],
|
||||
},
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. `ActionDefinition` type exists with `id`, `label`, `description?`, `inputSchema?`
|
||||
2. `ActionResult` type exists with `ok`, `data?`, `error?`
|
||||
3. `ItemAction` type exists with `actionId`, `label?`, `params?`
|
||||
4. `FeedSource.listActions()` is a required method returning `Record<string, ActionDefinition>` (empty record if no actions)
|
||||
5. `FeedSource.executeAction()` is a required method (no-op for sources without actions)
|
||||
6. `FeedItem.actions` is an optional readonly array of `ItemAction`
|
||||
7. `FeedEngine.executeAction()` routes to correct source, returns `ActionResult`
|
||||
8. `FeedEngine.listActions()` aggregates actions from all sources
|
||||
9. Existing tests pass unchanged (all changes are additive)
|
||||
10. New tests: action execution, unknown action ID, unknown source ID, source without actions, `listActions()` aggregation
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Create `action.ts` in `aris-core/src` with `ActionDefinition`, `ActionResult`, `ItemAction`
|
||||
2. Add optional `actions` and `executeAction` to `FeedSource` interface in `feed-source.ts`
|
||||
3. Add optional `actions` field to `FeedItem` interface in `feed.ts`
|
||||
4. Add `executeAction()` and `listActions()` to `FeedEngine` in `feed-engine.ts`
|
||||
5. Export new types from `aris-core/index.ts`
|
||||
6. Add tests for `FeedEngine.executeAction()` routing
|
||||
7. Add tests for `FeedEngine.listActions()` aggregation
|
||||
8. Add tests for error cases (unknown action, unknown source, source without actions)
|
||||
9. Update source IDs to reverse-domain format (`"location"` → `"aris.location"`, etc.) across all source packages
|
||||
10. Migrate `LocationSource.pushLocation()` → action `update-location` on `aris.location`
|
||||
11. Migrate `TflSource.setLinesOfInterest()` → action `set-lines-of-interest` on `aris.tfl`
|
||||
12. Add `async listActions() { return {} }` and no-op `executeAction()` to sources without actions (WeatherSource, GoogleCalendarSource, AppleCalendarSource)
|
||||
13. Update any tests or code referencing old source IDs
|
||||
14. Run all tests to confirm nothing breaks
|
||||
|
||||
## What This Defers
|
||||
|
||||
- Transport layer (JSON-RPC over HTTP/WebSocket) — built when remote sources are needed
|
||||
- `RemoteFeedSource` adapter — mechanical once transport exists
|
||||
- MCP adapter — wraps MCP servers as FeedSource
|
||||
- Runtime schema validation of action params
|
||||
- Action permissions / confirmation UI
|
||||
- Source discovery / registry API
|
||||
- Backend service consolidation (separate spec, depends on this one)
|
||||
Reference in New Issue
Block a user