@scardis/omnifocus-mcp 0.1.0 → 0.1.2

package/openspec/changes/archive/2026-04-09-project-filtering/specs/project-filtering/spec.md

@@ -1,66 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Filter list_projects results
-
-The system SHALL allow `list_projects` to accept an optional `filter` object that restricts which projects are returned. All filter fields are optional and combine as AND conditions. When `filter.status` is omitted, the tool SHALL exclude projects with status `done` or `dropped` by default.
-
-Filter fields:
-- `status` (array of ProjectStatus): return only projects whose status is in the array; overrides the default exclusion of done/dropped
-- `folderId` (string): return only projects within the specified folder or any of its descendant folders; throws not-found if the folder ID does not exist
-- `flagged` (boolean): when `true`, return only flagged projects
-
-#### Scenario: Default excludes done and dropped projects
-- **WHEN** `list_projects` is called with no filter
-- **THEN** the tool returns only projects with status `active` or `onHold`
-
-#### Scenario: Filter by status array
-- **WHEN** `list_projects` is called with `{ filter: { status: ["active"] } }`
-- **THEN** the tool returns only active projects
-
-#### Scenario: Explicit status filter retrieves done projects
-- **WHEN** `list_projects` is called with `{ filter: { status: ["done"] } }`
-- **THEN** the tool returns completed projects (the default exclusion does not apply)
-
-#### Scenario: Filter by folderId returns projects in subtree
-- **WHEN** `list_projects` is called with `{ filter: { folderId: "abc123" } }`
-- **THEN** the tool returns only projects whose parent folder chain includes the specified folder
-
-#### Scenario: Non-existent folderId returns not-found error
-- **WHEN** `list_projects` is called with a `folderId` that does not correspond to any folder
-- **THEN** the tool returns a structured not-found error
-
-#### Scenario: Filter by flagged
-- **WHEN** `list_projects` is called with `{ filter: { flagged: true } }`
-- **THEN** the tool returns only flagged projects, excluding done and dropped projects
-
-#### Scenario: Combined filters act as AND
-- **WHEN** `list_projects` is called with `{ filter: { status: ["active"], flagged: true } }`
-- **THEN** the tool returns only projects that are both active AND flagged
-
-### Requirement: Limit list_projects results
-
-The system SHALL allow `list_projects` to accept an optional `limit` integer that caps the number of projects returned. When `limit` is omitted, a default of 100 SHALL apply.
-
-#### Scenario: Default limit of 100
-- **WHEN** `list_projects` is called without a `limit` and more than 100 projects match
-- **THEN** the tool returns at most 100 projects
-
-#### Scenario: Custom limit
-- **WHEN** `list_projects` is called with `{ limit: 20 }`
-- **THEN** the tool returns at most 20 projects
-
-### Requirement: Enriched project summary includes flagged and folderId
-
-The `ProjectSummary` returned by `list_projects` SHALL include `flagged` (boolean) and `folderId` (string or null) in addition to existing fields. `folderId` SHALL be the direct parent folder's `id.primaryKey`, or `null` for top-level projects.
-
-#### Scenario: Summary includes flagged
-- **WHEN** `list_projects` returns a flagged project
-- **THEN** the project summary includes `flagged: true`
-
-#### Scenario: Summary includes folderId for nested project
-- **WHEN** `list_projects` returns a project inside a folder
-- **THEN** the project summary includes `folderId` set to the parent folder's ID
-
-#### Scenario: Summary includes folderId null for top-level project
-- **WHEN** `list_projects` returns a top-level project with no containing folder
-- **THEN** the project summary includes `folderId: null`

package/openspec/changes/archive/2026-04-09-project-filtering/specs/project-management/spec.md

@@ -1,13 +0,0 @@
-## MODIFIED Requirements
-
-### Requirement: List projects
-
-The system SHALL provide a `list_projects` tool that returns projects in the OmniFocus database as an array of summaries, each containing `{id, name, folderPath, folderId, status, type, flagged}`. The `status` field SHALL be one of `"active" | "onHold" | "done" | "dropped"`. The `type` field SHALL be one of `"parallel" | "sequential" | "singleActions"`. The `folderPath` field SHALL use the canonical ` ▸ ` separator and SHALL be an empty string for top-level projects. The `folderId` field SHALL be the direct parent folder's ID or `null` for top-level projects. The tool SHALL accept an optional `filter` object (see project-filtering spec) and an optional `limit` integer (default 100). When no `filter.status` is provided, projects with status `done` or `dropped` SHALL be excluded by default.
-
-#### Scenario: Active and on-hold projects returned by default
-- **WHEN** `list_projects` is called with no arguments
-- **THEN** the tool returns only projects with status `active` or `onHold`, each with id, name, folderPath, folderId, status, type, and flagged populated
-
-#### Scenario: Single Actions list is reported with correct type
-- **WHEN** the database contains a Single Actions list project
-- **THEN** that project appears in the result with `type: "singleActions"`, never as `"parallel"` or `"sequential"`

package/openspec/changes/archive/2026-04-09-project-filtering/tasks.md

@@ -1,41 +0,0 @@
-## 1. Schema changes (src/schemas/)
-
-- [x] 1.1 Add `flagged: z.boolean()` and `folderId: IdSchema.nullable()` to `ProjectSummary` in `shapes.ts`
-- [x] 1.2 Define `ListProjectsFilter` zod schema: `{ status: z.array(ProjectStatus).optional(), folderId: IdSchema.optional(), flagged: z.literal(true).optional() }`
-- [x] 1.3 Export `ListProjectsFilter` from `src/schemas/index.ts`
-
-## 2. Snippet rewrite (src/snippets/list_projects.js)
-
-- [x] 2.1 Add `flagged` and `folderId` (parent folder's `id.primaryKey` or `null`) to the project mapping helper
-- [x] 2.2 Implement default status exclusion: when `args.filter?.status` is absent, exclude `Project.Status.Done` and `Project.Status.Dropped`
-- [x] 2.3 Implement `status` array filter: when `args.filter?.status` is provided, keep only projects whose status maps to one of the given strings
-- [x] 2.4 Implement `folderId` filter: resolve the folder by ID (throw `NotFoundError` if not found), then use `folder.flattenedProjects` to get the matching set before applying other filters
-- [x] 2.5 Implement `flagged` filter: when `args.filter?.flagged` is `true`, keep only flagged projects
-- [x] 2.6 Apply `args.limit` (default 100) as a slice after all filters
-
-## 3. Tool handler update (src/tools/listProjects.ts)
-
-- [x] 3.1 Add `filter: ListProjectsFilter.optional()` and `limit: z.number().int().positive().optional()` to `listProjectsSchema`
-- [x] 3.2 Pass `filter` and `limit` through to `runSnippet`
-- [x] 3.3 Update tool description to document filter params and new default-exclusion behavior
-
-## 4. Unit tests (test/unit/)
-
-- [x] 4.1 Search for any `ProjectSummary` fixtures in unit tests and add `flagged` and `folderId` fields
-- [x] 4.2 Add schema tests for `ListProjectsFilter`: valid filter passes; invalid status enum rejected; `flagged: false` rejected (must be literal `true` or absent)
-
-## 5. Integration tests (test/integration/)
-
-- [x] 5.1 `listProjectsFiltered.int.test.ts`: create projects with known properties; verify default excludes done/dropped projects
-- [x] 5.2 Verify `status` filter: create a completed project; confirm absent by default and present when `status: ["done"]` is passed
-- [x] 5.3 Verify `folderId` filter: confirm only projects in that folder's subtree are returned
-- [x] 5.4 Verify `flagged` filter: create flagged and unflagged projects; confirm only flagged returned
-- [x] 5.5 Verify `limit`: confirm result is capped
-- [x] 5.6 Verify enriched summary: returned projects include correct `flagged` and `folderId` fields
-
-## 6. Verification
-
-- [x] 6.1 `npm run typecheck` clean
-- [x] 6.2 `npm test` (unit suite) clean
-- [x] 6.3 Manually run integration suite; verify fixture cleanup
-- [ ] 6.4 Connect to Claude Desktop; exercise filter queries against a real database

package/openspec/changes/archive/2026-04-09-tag-crud/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-09

package/openspec/changes/archive/2026-04-09-tag-crud/design.md

@@ -1,45 +0,0 @@
-## Context
-
-Tags in OmniJS form a tree (parent/child nesting) and have a `status` property (`active`, `onHold`, `dropped`). Write operations are straightforward. Deleting a tag with child tags removes the entire subtree; tasks that held the tag have it automatically removed by OmniFocus.
-
-OmniJS tag write operations:
-- `new Tag(name)` — creates a top-level tag
-- `new Tag(name, parentTag)` — creates a child tag nested under `parentTag`
-- `tag.name = "..."` — rename
-- `tag.status = Tag.Status.Active / OnHold / Dropped` — status transitions
-- `deleteObject(tag)` — removes the tag; child tags and task associations are cleaned up by OmniFocus automatically (unlike folders/projects, no manual cascade needed)
-
-## Goals / Non-Goals
-
-**Goals:**
-- Create top-level and child tags
-- Rename tags and change their status
-- Delete tags (OmniFocus handles the cascade automatically)
-
-**Non-Goals:**
-- Moving a tag to a different parent (separate `move-operations` change)
-
-## Decisions
-
-### Decision 1: `deleteObject(tag)` is safe without manual cascade
-
-Unlike folders, `deleteObject(tag)` in OmniJS removes the tag, its child tags, and all task/project tag associations automatically. No recursive snippet logic is needed.
-
-**Verification needed during implementation:** confirm child tags are removed and task associations are cleaned. If this proves incorrect, apply the folder recursive pattern.
-
-### Decision 2: `edit_tag` exposes both `name` and `status`
-
-Tags have a meaningful `status` (`active`, `onHold`, `dropped`) that users set intentionally. Unlike folder status (which is derived), tag status is directly writable and useful — e.g., putting a context tag on hold while travelling. Both `name` and `status` are optional fields in `edit_tag`.
-
-### Decision 3: `create_tag` placement via optional `parentTagId`
-
-- `parentTagId` omitted → top-level tag
-- `parentTagId` provided → child tag nested under that tag
-
-Same pattern as `create_folder` with `parentFolderId`.
-
-## Risks / Trade-offs
-
-- **Deleting a tag with many children** — automatic cascade by OmniFocus; no performance concern beyond normal `deleteObject` overhead.
-- **`tag.status` enum values** — OmniJS uses `Tag.Status.Active`, `Tag.Status.OnHold`, `Tag.Status.Dropped`. Snippet must map input strings to the correct enum members.
-- **Renaming a tag used in many tasks** — OmniFocus updates all associations automatically (tags are objects with stable IDs, not strings).

package/openspec/changes/archive/2026-04-09-tag-crud/proposal.md

@@ -1,28 +0,0 @@
-## Why
-
-The bootstrap change delivered read-only tag access. Callers can read the tag hierarchy but cannot create new tags, rename existing ones, or delete them — blocking workflows that involve tagging tasks with tags that don't yet exist or maintaining the tag taxonomy.
-
-## What Changes
-
-- Add `create_tag` tool: create a top-level tag or a child tag nested under an existing tag
-- Add `edit_tag` tool: rename a tag
-- Add `delete_tag` tool: permanently delete a tag; tasks that held the tag have it removed (tool description instructs the AI to confirm with the user before invoking)
-
-## Capabilities
-
-### New Capabilities
-
-- `tag-write`: Create, rename, and permanently delete OmniFocus tags
-
-### Modified Capabilities
-
-_(none — existing `tag-management` read requirements are unchanged)_
-
-## Impact
-
-- 3 new MCP tools registered in `src/server.ts`
-- 3 new tool handler files in `src/tools/`
-- 3 new OmniJS snippets in `src/snippets/`
-- `ALLOWED_SNIPPETS` allowlist in `src/runtime/snippetLoader.ts` must be extended
-- Deleting a tag with child tags also removes all descendants; tool description should note this
-- Integration tests will mutate real OmniFocus data (scoped to fixture folder per existing pattern)

package/openspec/changes/archive/2026-04-09-tag-crud/specs/tag-write/spec.md

@@ -1,49 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Create tag
-
-The system SHALL provide a `create_tag` tool that creates a new OmniFocus tag and returns its full detail record. The tool SHALL accept `{name: string, parentTagId?: string}`. If `parentTagId` is provided the tag SHALL be created nested under that tag; otherwise it SHALL be created at the top level.
-
-#### Scenario: Create top-level tag
-- **WHEN** `create_tag` is called with `{name: "Waiting"}` and no `parentTagId`
-- **THEN** the tool creates the tag at the top level and returns its full detail record including a stable `id`
-
-#### Scenario: Create child tag
-- **WHEN** `create_tag` is called with `{name: "Email", parentTagId: "abc123"}`
-- **THEN** the tool creates the tag nested under the specified parent tag and returns its full detail record with `path` and `parentId` set correctly
-
-#### Scenario: Non-existent parent tag returns not-found error
-- **WHEN** `create_tag` is called with a `parentTagId` that does not correspond to any tag
-- **THEN** the tool returns a structured not-found error
-
-### Requirement: Edit tag
-
-The system SHALL provide an `edit_tag` tool that modifies an existing tag and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, status?: "active" | "onHold" | "dropped"}`. Fields omitted SHALL be left unchanged.
-
-#### Scenario: Rename a tag
-- **WHEN** `edit_tag` is called with `{id: "abc123", name: "Delegated"}`
-- **THEN** the tag's name is updated and the tool returns the updated detail record
-
-#### Scenario: Put tag on hold
-- **WHEN** `edit_tag` is called with `{id: "abc123", status: "onHold"}`
-- **THEN** the tag's status becomes `"onHold"` and the tool returns the updated detail record
-
-#### Scenario: Non-existent tag returns not-found error
-- **WHEN** `edit_tag` is called with an ID that does not correspond to any tag
-- **THEN** the tool returns a structured not-found error
-
-### Requirement: Delete tag
-
-The system SHALL provide a `delete_tag` tool that permanently deletes a tag and all its child tags using OmniJS `deleteObject()`. Tasks and projects that held the tag have it removed automatically by OmniFocus. The tool description SHALL instruct the AI to confirm with the user before invoking, noting that child tags are also deleted.
-
-#### Scenario: Delete a tag
-- **WHEN** `delete_tag` is called with the ID of an existing tag
-- **THEN** the tag is permanently removed from OmniFocus, all tasks that held it have it removed, and the tool returns a confirmation envelope
-
-#### Scenario: Delete tag with children removes entire subtree
-- **WHEN** `delete_tag` is called with the ID of a tag that has child tags
-- **THEN** the tag and all its descendant tags are deleted
-
-#### Scenario: Non-existent tag returns not-found error
-- **WHEN** `delete_tag` is called with an ID that does not correspond to any tag
-- **THEN** the tool returns a structured not-found error

package/openspec/changes/archive/2026-04-09-tag-crud/tasks.md

@@ -1,41 +0,0 @@
-## 1. Snippets (src/snippets/)
-
-- [x] 1.1 `create_tag.js`: accept `{name, parentTagId?}`; if `parentTagId` provided resolve parent tag by ID and throw `NotFoundError` if missing; create `new Tag(name)` or `new Tag(name, parentTag)`; return full tag detail envelope
-- [x] 1.2 `edit_tag.js`: accept `{id, name?, status?}`; resolve tag by ID; apply only provided fields; map `status` string to `Tag.Status` enum member; return updated full tag detail envelope
-- [x] 1.3 `delete_tag.js`: accept `{id}`; resolve tag by ID; call `deleteObject(tag)` (OmniFocus handles child tag and association cleanup automatically); return `{ok: true, data: {id}}`
-
-## 2. Snippet allowlist
-
-- [x] 2.1 Add `create_tag`, `edit_tag`, `delete_tag` to `ALLOWED_SNIPPETS` in `src/runtime/snippetLoader.ts`
-
-## 3. Schemas (src/schemas/shapes.ts)
-
-- [x] 3.1 Define `CreateTagInput` zod schema: `{name: z.string().min(1), parentTagId: IdSchema.optional()}`
-- [x] 3.2 Define `EditTagInput` zod schema: `{id: IdSchema, name: z.string().min(1).optional(), status: TagStatus.optional()}`; add `.refine()` requiring at least one of `name` or `status`
-
-## 4. Tool handlers (src/tools/)
-
-- [x] 4.1 `createTag.ts`: validate input with `CreateTagInput`; invoke `runSnippet("create_tag", args)`; validate result against `TagDetail`; return
-- [x] 4.2 `editTag.ts`: validate input with `EditTagInput`; invoke `runSnippet("edit_tag", args)`; validate result against `TagDetail`; return
-- [x] 4.3 `deleteTag.ts`: input `{id: IdSchema}`; tool description MUST state the AI should confirm with the user before invoking and note that child tags are also permanently deleted; invoke `runSnippet("delete_tag", {id})`; return confirmation
-
-## 5. Server registration
-
-- [x] 5.1 Export all three new tool definitions from `src/tools/index.ts`
-
-## 6. Unit tests (test/unit/)
-
-- [x] 6.1 `schemas.editTag.test.ts`: valid inputs pass; empty object (neither name nor status) rejected by refine; invalid status enum rejected
-
-## 7. Integration tests (test/integration/)
-
-- [x] 7.1 `createTag.int.test.ts`: create top-level tag; create child tag; verify `path`, `parentId`, `childTagIds`
-- [x] 7.2 `editTag.int.test.ts`: rename a tag; put tag on hold; verify status and name
-- [x] 7.3 `deleteTag.int.test.ts`: delete a tag; verify subsequent `get_tag` returns not-found; verify child tags also gone
-
-## 8. Verification
-
-- [x] 8.1 `npm run typecheck` clean
-- [x] 8.2 `npm test` (unit suite) clean
-- [x] 8.3 Manually run integration suite; verify fixture cleanup
-- [ ] 8.4 Connect to Claude Desktop; exercise all three tools against a real database

package/openspec/changes/archive/2026-04-09-task-crud/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-09

package/openspec/changes/archive/2026-04-09-task-crud/design.md

@@ -1,62 +0,0 @@
-## Context
-
-The bootstrap change established the JXA→OmniJS bridge, snippet pattern, and result protocol. All five write tools follow those same patterns. The key question for writes is: what does OmniJS expose for creating and mutating tasks, and what are the edge cases?
-
-OmniJS task write operations:
-- `new Task(name, position)` — creates a task; `position` is a `Project` or `Task` (for subtasks)
-- `task.name = "..."` — property assignment for most scalar fields
-- `task.markComplete()` — dedicated method (not property assignment)
-- `task.drop()` — dedicated method
-- `deleteObject(task)` — permanent deletion
-- Tags: `task.addTag(tag)` / `task.removeTag(tag)` — manipulate by Tag object, not ID
-
-## Goals / Non-Goals
-
-**Goals:**
-- Expose create, edit, complete, drop, and delete for tasks
-- Support inbox tasks (no project), project tasks, and subtasks
-- Edit any subset of fields in one call (fat edit — no single-field tools)
-- Permanently delete with a tool description that instructs the AI to confirm before invoking
-
-**Non-Goals:**
-- Moving tasks between projects/containers (separate `move-operations` change)
-- Recurrence rules (separate `recurrence` change)
-- Batch operations (separate change)
-
-## Decisions
-
-### Decision 1: Tag manipulation by ID, resolved inside the snippet
-
-Tags are assigned via `task.addTag(tagObject)` / `task.removeTag(tagObject)`, which require a live `Tag` object. The snippet will receive tag IDs and resolve them via `flattenedTags.find(t => t.id.primaryKey === id)` inline. This keeps the bridge contract clean (IDs only) without requiring a separate resolution round-trip.
-
-**Alternative considered:** Accept tag names. Rejected — names are ambiguous; IDs are stable.
-
-### Decision 2: `edit_task` replaces tags, not merges
-
-When `tagIds` is provided to `edit_task`, the snippet replaces the task's full tag set (remove all, add new). When `tagIds` is omitted, tags are untouched. This is the least surprising contract: callers who want to add one tag still need to pass the full desired set, but they can read it from `get_task` first.
-
-**Alternative considered:** Separate `add_tags` / `remove_tags` fields. Rejected — more surface area with no material benefit given that `get_task` is cheap.
-
-### Decision 3: `create_task` placement via optional `projectId` and `parentTaskId`
-
-- Both omitted → inbox
-- `projectId` only → task added to project root
-- `parentTaskId` only → subtask; inherits project from parent
-- Both provided → error (ambiguous placement; caller must choose)
-
-This mirrors how OmniFocus itself treats task placement.
-
-### Decision 4: `complete_task` and `drop_task` as separate tools from `edit_task`
-
-Status transitions in OmniJS require method calls (`markComplete()`, `drop()`), not property assignment. Exposing them as dedicated tools makes the intent unambiguous and avoids a complex status-to-method dispatch inside `edit_task`. It also makes tool descriptions cleaner for the LLM.
-
-### Decision 5: `delete_task` tool description as the confirmation guardrail
-
-The server executes `deleteObject(task)` unconditionally when called. The confirmation requirement is enforced through the MCP tool description, which instructs the AI to ask the user explicitly before invoking this tool. This is consistent with how MCP tool descriptions guide AI behavior.
-
-## Risks / Trade-offs
-
-- **Partial edit with bad field value** → OmniJS will throw; the error envelope propagates back as an `ExecutionError`. No partial writes occur because OmniJS is synchronous within `evaluateJavascript`.
-- **Tag ID not found during edit** → Snippet should throw a descriptive `NotFoundError` for the missing tag ID, not silently skip it.
-- **Inbox placement** → `new Task(name, inbox)` requires passing the `inbox` object. In OmniJS the inbox is accessible as `inbox` (bare global). Verified pattern from the read-side exploration.
-- **deleteObject on a task with subtasks** → OmniJS deletes the task and all subtasks. Tool description should note this.

package/openspec/changes/archive/2026-04-09-task-crud/proposal.md

@@ -1,29 +0,0 @@
-## Why
-
-The bootstrap change delivered read-only task access. Callers can observe tasks but cannot create, modify, complete, drop, or delete them — making the server unsuitable for any workflow that involves acting on tasks, not just reading them.
-
-## What Changes
-
-- Add `create_task` tool: create a task in a project, as a subtask, or in the inbox
-- Add `edit_task` tool: modify any subset of a task's scalar fields and tag assignments in a single call
-- Add `complete_task` tool: mark a task complete
-- Add `drop_task` tool: mark a task dropped
-- Add `delete_task` tool: permanently delete a task (tool description instructs the AI to confirm with the user before invoking)
-
-## Capabilities
-
-### New Capabilities
-
-- `task-write`: Create, edit, complete, drop, and permanently delete OmniFocus tasks
-
-### Modified Capabilities
-
-- `task-management`: Extend existing spec to add write requirements alongside the existing read requirements
-
-## Impact
-
-- 5 new MCP tools registered in `src/server.ts`
-- 5 new tool handler files in `src/tools/`
-- 5 new OmniJS snippets in `src/snippets/`
-- `ALLOWED_SNIPPETS` allowlist in `src/runtime/snippetLoader.ts` must be extended
-- Integration tests will mutate real OmniFocus data (scoped to fixture folder per existing pattern)

package/openspec/changes/archive/2026-04-09-task-crud/specs/task-management/spec.md

@@ -1,17 +0,0 @@
-## MODIFIED Requirements
-
-### Requirement: Get task by ID
-
-The system SHALL provide a `get_task` tool that accepts `{id: string}` and returns the full detail record of the named task, including `{id, name, note, status, flagged, deferDate, dueDate, completionDate, estimatedMinutes, containerId, containerType, tagIds, parentTaskId}`. The `parentTaskId` field SHALL be `null` for top-level tasks and SHALL contain the parent task's `id.primaryKey` for subtasks. If no task exists with that ID, the tool SHALL return a structured not-found error.
-
-#### Scenario: Existing task returns full detail
-- **WHEN** `get_task` is called with the ID of an existing task
-- **THEN** the tool returns the task's full detail record including all scalar fields, the list of tag IDs assigned to it, and `parentTaskId`
-
-#### Scenario: Subtask includes parentTaskId
-- **WHEN** `get_task` is called with the ID of a subtask
-- **THEN** the returned record includes `parentTaskId` set to the parent task's stable ID
-
-#### Scenario: Missing task returns not-found error
-- **WHEN** `get_task` is called with an ID that does not correspond to any task
-- **THEN** the tool returns a structured error with a not-found code and does not throw an unhandled exception

package/openspec/changes/archive/2026-04-09-task-crud/specs/task-write/spec.md

@@ -1,89 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Create task
-
-The system SHALL provide a `create_task` tool that creates a new OmniFocus task and returns its full detail record. The tool SHALL accept `{name: string, note?: string, flagged?: boolean, deferDate?: string, dueDate?: string, estimatedMinutes?: number, projectId?: string, parentTaskId?: string, tagIds?: string[]}`. Placement SHALL be determined as follows: if both `projectId` and `parentTaskId` are provided the tool SHALL return an error; if only `projectId` is provided the task is placed at the project root; if only `parentTaskId` is provided the task is created as a subtask inheriting its parent's project; if neither is provided the task is placed in the inbox.
-
-#### Scenario: Create inbox task
-- **WHEN** `create_task` is called with `{name: "Buy milk"}` and no `projectId` or `parentTaskId`
-- **THEN** the tool creates the task in the OmniFocus inbox and returns its full detail record including a stable `id`
-
-#### Scenario: Create task in a project
-- **WHEN** `create_task` is called with `{name: "Write tests", projectId: "abc123"}`
-- **THEN** the tool creates the task at the root of the specified project and returns its full detail record
-
-#### Scenario: Create subtask
-- **WHEN** `create_task` is called with `{name: "Review PR", parentTaskId: "xyz789"}`
-- **THEN** the tool creates the task as a child of the specified parent task and returns its full detail record
-
-#### Scenario: Ambiguous placement is rejected
-- **WHEN** `create_task` is called with both `projectId` and `parentTaskId`
-- **THEN** the tool returns a validation error before any snippet executes
-
-#### Scenario: Non-existent project returns not-found error
-- **WHEN** `create_task` is called with a `projectId` that does not correspond to any project
-- **THEN** the tool returns a structured not-found error
-
-### Requirement: Edit task
-
-The system SHALL provide an `edit_task` tool that modifies an existing task and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, note?: string, flagged?: boolean, deferDate?: string | null, dueDate?: string | null, estimatedMinutes?: number | null, tagIds?: string[]}`. Fields omitted from the call SHALL be left unchanged. When `tagIds` is provided it SHALL replace the task's entire tag set; when omitted, tags SHALL be unchanged. Passing `null` for a date or `estimatedMinutes` SHALL clear the field.
-
-#### Scenario: Edit a single field
-- **WHEN** `edit_task` is called with `{id: "abc123", flagged: true}`
-- **THEN** only the `flagged` field is changed; all other fields retain their previous values
-
-#### Scenario: Replace tag set
-- **WHEN** `edit_task` is called with `{id: "abc123", tagIds: ["t1", "t2"]}`
-- **THEN** the task's tags are set to exactly `["t1", "t2"]`, replacing any previously assigned tags
-
-#### Scenario: Clear a date field
-- **WHEN** `edit_task` is called with `{id: "abc123", dueDate: null}`
-- **THEN** the task's due date is cleared
-
-#### Scenario: Non-existent task returns not-found error
-- **WHEN** `edit_task` is called with an ID that does not correspond to any task
-- **THEN** the tool returns a structured not-found error
-
-#### Scenario: Non-existent tag ID returns not-found error
-- **WHEN** `edit_task` is called with a `tagIds` array containing an ID that does not correspond to any tag
-- **THEN** the tool returns a structured not-found error and the task is not modified
-
-### Requirement: Complete task
-
-The system SHALL provide a `complete_task` tool that marks an existing task complete using OmniJS `markComplete()` and returns the task's updated full detail record.
-
-#### Scenario: Complete an existing task
-- **WHEN** `complete_task` is called with the ID of an available task
-- **THEN** the task's status becomes `"complete"` and the tool returns the updated detail record
-
-#### Scenario: Non-existent task returns not-found error
-- **WHEN** `complete_task` is called with an ID that does not correspond to any task
-- **THEN** the tool returns a structured not-found error
-
-### Requirement: Drop task
-
-The system SHALL provide a `drop_task` tool that marks an existing task dropped using OmniJS `drop()` and returns the task's updated full detail record.
-
-#### Scenario: Drop an existing task
-- **WHEN** `drop_task` is called with the ID of an available task
-- **THEN** the task's status becomes `"dropped"` and the tool returns the updated detail record
-
-#### Scenario: Non-existent task returns not-found error
-- **WHEN** `drop_task` is called with an ID that does not correspond to any task
-- **THEN** the tool returns a structured not-found error
-
-### Requirement: Delete task
-
-The system SHALL provide a `delete_task` tool that permanently deletes a task and all its subtasks using OmniJS `deleteObject()`. The tool description SHALL instruct the AI to confirm with the user before invoking this tool, noting that deletion is permanent and includes all subtasks.
-
-#### Scenario: Delete an existing task
-- **WHEN** `delete_task` is called with the ID of an existing task
-- **THEN** the task and all its subtasks are permanently removed from OmniFocus and the tool returns a confirmation envelope
-
-#### Scenario: Delete task with subtasks removes all children
-- **WHEN** `delete_task` is called with the ID of a task that has subtasks
-- **THEN** the task and all descendant subtasks are deleted
-
-#### Scenario: Non-existent task returns not-found error
-- **WHEN** `delete_task` is called with an ID that does not correspond to any task
-- **THEN** the tool returns a structured not-found error

package/openspec/changes/archive/2026-04-09-task-crud/tasks.md

@@ -1,55 +0,0 @@
-## 1. Snippets (src/snippets/)
-
-- [x] 1.1 `create_task.js`: accept `{name, note?, flagged?, deferDate?, dueDate?, estimatedMinutes?, projectId?, parentTaskId?, tagIds?}`; resolve placement (inbox / project root / subtask); throw `ConflictError` if both `projectId` and `parentTaskId` provided; throw `NotFoundError` on missing project, parent task, or tag ID; return full task detail envelope
-- [x] 1.2 `edit_task.js`: accept `{id, name?, note?, flagged?, deferDate?, dueDate?, estimatedMinutes?, tagIds?}`; resolve task by ID; apply only provided fields; when `tagIds` present replace full tag set (remove all, add each by ID); pass `null` dates/estimatedMinutes to clear; return updated full detail envelope
-- [x] 1.3 `complete_task.js`: accept `{id}`; resolve task by ID; call `task.markComplete()`; return updated full detail envelope
-- [x] 1.4 `drop_task.js`: accept `{id}`; resolve task by ID; call `task.drop()`; return updated full detail envelope
-- [x] 1.5 `delete_task.js`: accept `{id}`; resolve task by ID; call `deleteObject(task)`; return `{ok: true, data: {id}}`
-
-## 2. Snippet allowlist
-
-- [x] 2.1 Add `create_task`, `edit_task`, `complete_task`, `drop_task`, `delete_task` to `ALLOWED_SNIPPETS` in `src/runtime/snippetLoader.ts`
-
-## 3. Schemas (src/schemas/shapes.ts)
-
-- [x] 3.1 Add `parentTaskId: z.string().nullable()` to `TaskDetail` schema
-- [x] 3.2 Define `CreateTaskInput` zod schema with all optional fields and the mutual-exclusion refinement for `projectId` + `parentTaskId`
-- [x] 3.3 Define `EditTaskInput` zod schema — `id` required, all other fields optional; date fields accept `string | null`; `estimatedMinutes` accepts `number | null`
-
-## 4. Tool handlers (src/tools/)
-
-- [x] 4.1 `createTask.ts`: validate input with `CreateTaskInput`; invoke `runSnippet("create_task", args)`; validate result against `TaskDetail`; return
-- [x] 4.2 `editTask.ts`: validate input with `EditTaskInput`; invoke `runSnippet("edit_task", args)`; validate result against `TaskDetail`; return
-- [x] 4.3 `completeTask.ts`: input `{id: IdSchema}`; invoke `runSnippet("complete_task", {id})`; validate result against `TaskDetail`; return
-- [x] 4.4 `dropTask.ts`: input `{id: IdSchema}`; invoke `runSnippet("drop_task", {id})`; validate result against `TaskDetail`; return
-- [x] 4.5 `deleteTask.ts`: input `{id: IdSchema}`; tool description MUST state the AI should confirm with the user before invoking and note that deletion is permanent and includes all subtasks; invoke `runSnippet("delete_task", {id})`; return confirmation
-
-## 5. Server registration
-
-- [x] 5.1 Export all five new tool definitions from `src/tools/index.ts`
-- [x] 5.2 Verify `src/server.ts` picks them up via the `allTools` barrel (no change needed if barrel is already dynamic)
-
-## 6. get_task update
-
-- [x] 6.1 Update `src/snippets/get_task.js` to include `parentTaskId` in the returned detail (`t.parentTask ? t.parentTask.id.primaryKey : null`)
-- [x] 6.2 Update `src/tools/getTask.ts` to validate against the updated `TaskDetail` schema
-
-## 7. Unit tests (test/unit/)
-
-- [x] 7.1 `schemas.createTask.test.ts`: valid inputs pass; both `projectId` + `parentTaskId` rejected; missing name rejected; null dates accepted in edit schema
-- [x] 7.2 `tools.deleteTask.test.ts`: verify tool description contains confirmation language
-
-## 8. Integration tests (test/integration/)
-
-- [x] 8.1 `createTask.int.test.ts`: create inbox task, verify returned ID; create project task, verify containerId; create subtask, verify parentTaskId
-- [x] 8.2 `editTask.int.test.ts`: edit name; edit flags; replace tag set; clear due date
-- [x] 8.3 `completeTask.int.test.ts`: complete a task, verify status = `"complete"`
-- [x] 8.4 `dropTask.int.test.ts`: drop a task, verify status = `"dropped"`
-- [x] 8.5 `deleteTask.int.test.ts`: delete a task, verify subsequent `get_task` returns not-found
-
-## 9. Verification
-
-- [x] 9.1 `npm run typecheck` clean
-- [x] 9.2 `npm test` (unit suite) clean
-- [x] 9.3 Manually run integration suite; verify fixture cleanup
-- [ ] 9.4 Connect to Claude Desktop; exercise all five tools against a real database

package/openspec/changes/archive/2026-04-09-task-filtering/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-09

package/openspec/changes/archive/2026-04-09-task-filtering/design.md

@@ -1,61 +0,0 @@
-## Context
-
-`list_tasks` currently fetches all tasks in scope and returns a flat `TaskSummary` array with no server-side filtering. For large databases, `scope: { all: true }` can return thousands of tasks — far too many for an LLM to reason over. Filtering must happen inside the OmniJS snippet before data crosses the JXA bridge; post-hoc filtering in TypeScript would still pay the full serialization cost.
-
-`TaskSummary` currently omits `dueDate` and `tagIds`. Without these, filtered results are opaque: if the LLM asks "what's due today?" it can't present due dates in its response without issuing a `get_task` call per result.
-
-## Goals / Non-Goals
-
-**Goals:**
-- Filter tasks by `flagged`, `status[]`, `tagId`, and `dueBeforeDate` inside the snippet
-- Enrich `TaskSummary` with `dueDate` and `tagIds`
-- Change default behavior: exclude `complete` and `dropped` tasks when no `status` filter is provided
-- Cap results with a configurable `limit` (default 200)
-
-**Non-Goals:**
-- Multi-tag filtering with AND/OR semantics (future work)
-- Full-text search on task name or note
-- Pagination / cursor-based continuation (hard cap only)
-- Filtering `list_projects` (separate change)
-
-## Decisions
-
-### Decision 1: Filter in snippet, not TypeScript
-
-All filter logic runs inside `evaluateJavascript`. The TypeScript layer passes filter args through and validates the schema. This avoids deserializing thousands of tasks only to discard most of them.
-
-Alternative considered: filter in TS. Rejected because the JXA serialization cost is paid per-task regardless — a 5000-task DB would serialize all 5000 even if only 10 match.
-
-### Decision 2: Enrich TaskSummary with dueDate and tagIds
-
-`TaskSummary` gains two fields:
-- `dueDate: string | null` — ISO datetime
-- `tagIds: string[]`
-
-These are the fields most likely to appear in filtering queries and most useful to display in results. Other detail fields (`note`, `deferDate`, `estimatedMinutes`) remain in `TaskDetail` only.
-
-This is a non-breaking addition to the shape — existing consumers receive new optional fields.
-
-### Decision 3: Default excludes complete and dropped
-
-When `filter.status` is omitted, the snippet filters out `Task.Status.Completed` and `Task.Status.Dropped`. This is a breaking behavior change but the correct default for LLM-driven queries. The previous default (return everything) was only useful for bulk inspection, which can still be achieved with `status: ["available", "blocked", "dueSoon", "next", "overdue", "complete", "dropped"]`.
-
-### Decision 4: Status filter as array, tag filter as single ID
-
-`status` accepts an array of `TaskStatus` values. This lets callers express compound queries ("available OR overdue") in a single call.
-
-`tagId` accepts a single ID — the 80% use case. Multi-tag AND/OR filtering adds significant complexity for uncertain benefit in v1.
-
-### Decision 5: dueBeforeDate is inclusive
-
-`dueBeforeDate` matches tasks where `task.dueDate <= dueBeforeDate`. "Due before end of today" is expressed as the end-of-day ISO timestamp. Null due dates never match.
-
-### Decision 6: limit default 200, passed as snippet arg
-
-The limit is enforced inside the snippet (slice after filtering) so the cap applies before serialization. Default 200. Callers may increase it up to any value — there is no server-side maximum, just the JXA timeout.
-
-## Risks / Trade-offs
-
-- **Breaking default behavior** — consumers that relied on `list_tasks` returning complete tasks will see a behavior change. Risk is low: this is a local MCP server with a single consumer (Claude Desktop), and the new default is strictly more useful.
-- **tagId filter requires flattenedTags lookup** — to check `task.tags`, OmniJS traverses the tag tree. On databases with thousands of tags this is fast in practice but not free.
-- **limit does not paginate** — if a user has 500 overdue tasks and limit is 200, they see the first 200 with no way to retrieve the rest. Acceptable for v1; pagination is future work.