obsidian-accomplishments-mcp 0.1.9 → 0.1.11

package/dist/tools/tool-types.d.ts

@@ -0,0 +1,703 @@
+/**
+ * V2 MCP Tool Type Definitions
+ *
+ * Input/output types for all V2 MCP tools.
+ */
+import { EntityId, EntityType, EntityStatus, Priority } from '../models/v2-types.js';
+export type { EntityStatus, Priority };
+/** Workstream identifier (string alias for clarity) */
+export type Workstream = string;
+export interface EntitySummary {
+    id: EntityId;
+    type: EntityType;
+    title: string;
+    status: EntityStatus;
+    workstream: Workstream;
+    parent?: {
+        id: EntityId;
+        title: string;
+    };
+    children_count?: number;
+    last_updated: string;
+}
+export interface EntityFull extends EntitySummary {
+    content: string;
+    priority?: Priority;
+    dependencies?: {
+        blocks: EntityId[];
+        blocked_by: EntityId[];
+    };
+    task_progress?: {
+        total: number;
+        completed: number;
+    };
+    acceptance_criteria?: string[];
+    tasks?: TaskInfo[];
+    children?: EntitySummary[];
+    dependency_details?: {
+        blocks: EntitySummary[];
+        blocked_by: EntitySummary[];
+    };
+    implementation_context?: {
+        required: EntitySummary[];
+        reference: EntitySummary[];
+        assumes: string[];
+    };
+    documents?: EntityId[];
+    documented_by?: EntityId[];
+    implemented_by?: EntityId[];
+    decided_by?: EntityId[];
+    test_refs?: string[];
+    user_story?: string;
+    tier?: string;
+    phase?: string;
+}
+export interface TaskInfo {
+    title: string;
+    goal: string;
+    status: string;
+    estimate_hrs?: number;
+    actual_hrs?: number;
+}
+export interface CreateEntityInput {
+    type: EntityType;
+    data: {
+        title: string;
+        workstream: Workstream;
+        parent?: EntityId;
+        depends_on?: EntityId[];
+        implements?: EntityId[];
+        enables?: EntityId[];
+        [key: string]: unknown;
+    };
+    options?: {
+        canvas_source?: string;
+        add_to_canvas?: boolean;
+    };
+}
+export interface CreateEntityOutput {
+    id: EntityId;
+    entity: EntityFull;
+    dependencies_created: number;
+    canvas_node_added: boolean;
+    /** Messages from automatic processing (e.g., workstream normalization) */
+    messages?: string[];
+}
+export interface UpdateEntityInput {
+    id: EntityId;
+    data?: Record<string, unknown>;
+    add_dependencies?: EntityId[];
+    remove_dependencies?: EntityId[];
+    add_to?: {
+        implements?: EntityId[];
+        affects?: EntityId[];
+    };
+    remove_from?: {
+        implements?: EntityId[];
+        affects?: EntityId[];
+    };
+    status?: EntityStatus;
+    status_note?: string;
+    cascade?: boolean;
+    archived?: boolean;
+    archive_options?: {
+        force?: boolean;
+        cascade?: boolean;
+        archive_folder?: string;
+        remove_from_canvas?: boolean;
+        canvas_source?: string;
+    };
+    restore_options?: {
+        restore_children?: boolean;
+        add_to_canvas?: boolean;
+        canvas_source?: string;
+    };
+}
+/** Represents a single field change in an update operation */
+export interface FieldChange {
+    field: string;
+    before: unknown;
+    after: unknown;
+    /** For array fields: items added */
+    added?: unknown[];
+    /** For array fields: items removed */
+    removed?: unknown[];
+}
+export interface UpdateEntityOutput {
+    id: EntityId;
+    entity: EntityFull;
+    /** List of field changes made (before/after diff) */
+    changes?: FieldChange[];
+    dependencies_added: number;
+    dependencies_removed: number;
+    /** Messages from automatic processing (e.g., workstream normalization) */
+    messages?: string[];
+    status_changed?: {
+        old_status: EntityStatus;
+        new_status: EntityStatus;
+        cascaded_updates: EntityId[];
+    };
+    archive_result?: {
+        archived: boolean;
+        archive_path?: string;
+        archived_children?: EntityId[];
+    };
+    restore_result?: {
+        restored: boolean;
+        restored_children?: EntityId[];
+    };
+}
+export interface UpdateEntityStatusInput {
+    id: EntityId;
+    status: EntityStatus;
+    note?: string;
+    cascade?: boolean;
+}
+export interface UpdateEntityStatusOutput {
+    id: EntityId;
+    old_status: EntityStatus;
+    new_status: EntityStatus;
+    cascaded_updates: EntityId[];
+}
+export interface ArchiveEntityInput {
+    id: EntityId;
+    force?: boolean;
+    remove_from_canvas?: boolean;
+    canvas_source?: string;
+}
+export interface ArchiveEntityOutput {
+    id: EntityId;
+    archived: boolean;
+    archive_path: string;
+}
+export interface ArchiveMilestoneInput {
+    milestone_id: EntityId;
+    archive_folder?: string;
+    remove_from_canvas?: boolean;
+    canvas_source?: string;
+}
+export interface ArchiveMilestoneOutput {
+    milestone_id: EntityId;
+    archived_entities: {
+        milestones: EntityId[];
+        stories: EntityId[];
+        tasks: EntityId[];
+    };
+    total_archived: number;
+    archive_path: string;
+}
+export interface RestoreFromArchiveInput {
+    id: EntityId;
+    restore_children?: boolean;
+    add_to_canvas?: boolean;
+    canvas_source?: string;
+}
+export interface RestoreFromArchiveOutput {
+    id: EntityId;
+    restored: boolean;
+    restored_children: EntityId[];
+}
+/** Operation type for batch_update */
+export type BatchOpType = 'create' | 'update' | 'archive';
+/** Single operation in a batch_update call */
+export interface BatchOp {
+    /** Client-provided ID for idempotency and cross-reference within the batch */
+    client_id: string;
+    /** Operation type */
+    op: BatchOpType;
+    /** Entity type (required for create) */
+    type?: EntityType;
+    /** Entity ID (required for update/archive) */
+    id?: EntityId;
+    /** Payload for the operation */
+    payload: {
+        title?: string;
+        workstream?: string;
+        parent?: string;
+        depends_on?: string[];
+        implements?: string[];
+        enables?: string[];
+        status?: EntityStatus;
+        content?: string;
+        priority?: Priority;
+        archived?: boolean;
+        cascade?: boolean;
+        [key: string]: unknown;
+    };
+}
+/** Input for batch_update tool */
+export interface BatchUpdateInput {
+    /** Array of operations to perform */
+    ops: BatchOp[];
+    /** Options for the batch operation */
+    options?: {
+        /** If true, rollback all on any failure. Default: false */
+        atomic?: boolean;
+        /** Add created entities to canvas */
+        add_to_canvas?: boolean;
+        /** Canvas file path */
+        canvas_source?: string;
+        /** If true, include full entity data in results. Default: false */
+        include_entities?: boolean;
+        /** Fields to include when include_entities is true. If not specified, returns all fields. */
+        fields?: EntityField[];
+        /** If true, preview changes without executing them. Default: false */
+        dry_run?: boolean;
+    };
+}
+/** Preview of changes for dry_run mode */
+export interface DryRunPreview {
+    /** Client-provided ID */
+    client_id: string;
+    /** Entity ID (for updates/archives) */
+    id?: EntityId;
+    /** Operation type */
+    op: 'create' | 'update' | 'archive';
+    /** Predicted changes */
+    changes: FieldChange[];
+    /** Validation errors (if any) */
+    validation_errors: string[];
+}
+/** Result of a single operation in batch_update */
+export interface BatchOpResult {
+    /** Client-provided ID */
+    client_id: string;
+    /** Operation status */
+    status: 'ok' | 'error';
+    /** Entity ID (for successful creates/updates) */
+    id?: EntityId;
+    /** Error details (for failed operations) */
+    error?: {
+        code: string;
+        message: string;
+        field?: string;
+    };
+    /** Entity data (when include_entities option is true) */
+    entity?: Partial<EntityFull>;
+}
+/** Output for batch_update tool */
+export interface BatchUpdateOutput {
+    /** Results for each operation */
+    results: BatchOpResult[];
+    /** Summary of the batch operation */
+    summary: {
+        total: number;
+        succeeded: number;
+        failed: number;
+    };
+    /** Dry run mode indicator */
+    dry_run?: boolean;
+    /** Preview of changes (only in dry_run mode) */
+    would_update?: DryRunPreview[];
+}
+export interface GetProjectOverviewInput {
+    include_completed?: boolean;
+    include_archived?: boolean;
+    canvas_source?: string;
+    workstream?: Workstream;
+    group_by?: 'status' | 'type' | 'priority';
+}
+export interface GetProjectOverviewOutput {
+    summary: {
+        milestones: {
+            total: number;
+            completed: number;
+            in_progress: number;
+            blocked: number;
+        };
+        stories: {
+            total: number;
+            completed: number;
+            in_progress: number;
+            blocked: number;
+        };
+        tasks: {
+            total: number;
+            completed: number;
+            in_progress: number;
+            blocked: number;
+        };
+        decisions: {
+            total: number;
+            pending: number;
+            decided: number;
+        };
+        documents: {
+            total: number;
+            draft: number;
+            approved: number;
+        };
+    };
+    workstreams: Record<string, {
+        health: 'healthy' | 'at_risk' | 'blocked';
+        progress_percent: number;
+        blocked_count: number;
+    }>;
+    pending_decisions: number;
+    ready_for_implementation: number;
+    workstream_detail?: {
+        workstream: Workstream;
+        summary: {
+            total: number;
+            by_status: Record<string, number>;
+            by_type: Record<string, number>;
+            blocked_count: number;
+            cross_workstream_dependencies: number;
+        };
+        groups: Array<{
+            group_key: string;
+            entities: EntitySummary[];
+        }>;
+        blocking_other_workstreams: EntitySummary[];
+        blocked_by_other_workstreams: EntitySummary[];
+    };
+}
+export interface GetWorkstreamStatusInput {
+    workstream: Workstream;
+    include_completed?: boolean;
+    group_by?: 'status' | 'type' | 'priority';
+}
+export interface GetWorkstreamStatusOutput {
+    workstream: Workstream;
+    summary: {
+        total: number;
+        by_status: Record<string, number>;
+        by_type: Record<string, number>;
+        blocked_count: number;
+        cross_workstream_dependencies: number;
+    };
+    groups: Array<{
+        group_key: string;
+        entities: EntitySummary[];
+    }>;
+    blocking_other_workstreams: EntitySummary[];
+    blocked_by_other_workstreams: EntitySummary[];
+}
+export interface AnalyzeProjectStateInput {
+    workstream?: Workstream;
+    focus?: 'blockers' | 'actions' | 'both';
+    depth?: 'summary' | 'detailed';
+}
+export interface AnalyzeProjectStateOutput {
+    health: {
+        overall: 'healthy' | 'at_risk' | 'blocked';
+        workstreams: Record<string, {
+            status: string;
+            progress: number;
+            blocker_count: number;
+        }>;
+    };
+    blockers: {
+        critical_path: Array<{
+            blocker: EntitySummary;
+            impact: {
+                directly_blocks: EntityId[];
+                cascade_blocks: EntityId[];
+                total_blocked: number;
+                workstreams_affected: Workstream[];
+            };
+            suggested_resolution: string;
+            days_blocked: number;
+        }>;
+        by_type: {
+            pending_decisions: EntitySummary[];
+            incomplete_specs: EntitySummary[];
+            external_dependencies: EntitySummary[];
+        };
+        stale_items: EntitySummary[];
+    };
+    suggested_actions: Array<{
+        priority: number;
+        action: string;
+        reason: string;
+        effort: 'low' | 'medium' | 'high';
+        owner_hint: string;
+    }>;
+    stats: {
+        decisions_pending: number;
+        specs_ready: number;
+        items_blocked: number;
+        items_completed_this_week: number;
+    };
+}
+export interface SearchEntitiesInput {
+    query?: string;
+    from_id?: EntityId;
+    direction?: 'up' | 'down' | 'siblings' | 'dependencies';
+    depth?: number;
+    filters?: {
+        type?: EntityType[];
+        status?: EntityStatus[];
+        workstream?: Workstream[];
+        archived?: boolean;
+    };
+    limit?: number;
+    offset?: number;
+    include_content?: boolean;
+    fields?: EntityField[];
+}
+/** Search result item - fields are dynamic based on input.fields */
+export interface SearchResultItem {
+    id: EntityId;
+    type?: EntityType;
+    title?: string;
+    status?: EntityStatus;
+    workstream?: Workstream;
+    relevance_score?: number;
+    snippet?: string;
+    parent?: EntityId | {
+        id: EntityId;
+        title: string;
+    };
+    path?: string;
+    last_updated?: string;
+    priority?: string;
+    phase?: string;
+    tier?: string;
+    content?: string;
+    [key: string]: unknown;
+}
+export interface SearchEntitiesOutput {
+    results: SearchResultItem[];
+    total_matches: number;
+    pagination?: {
+        offset: number;
+        limit: number;
+        has_more: boolean;
+    };
+    origin?: EntitySummary;
+    path_description?: string;
+}
+/**
+ * Available fields for get_entity:
+ * - id, type, title, status, workstream, last_updated (always included in summary)
+ * - parent, children_count (basic hierarchy)
+ * - content (full markdown content)
+ * - effort, priority (planning fields)
+ * - dependencies (blocks/blocked_by IDs)
+ * - dependency_details (blocks/blocked_by with summaries)
+ * - task_progress (for stories)
+ * - acceptance_criteria (for stories/tasks)
+ * - children (child entity summaries)
+ * - implementation_context (for implementation handoff)
+ */
+export type EntityField = 'id' | 'type' | 'title' | 'status' | 'workstream' | 'last_updated' | 'parent' | 'children_count' | 'content' | 'priority' | 'dependencies' | 'dependency_details' | 'task_progress' | 'acceptance_criteria' | 'children' | 'implementation_context' | 'documents' | 'documented_by' | 'implemented_by' | 'decided_by' | 'test_refs' | 'user_story' | 'tier' | 'phase';
+export interface GetEntityInput {
+    id: EntityId;
+    /** Fields to include in response. If not specified, returns summary fields. */
+    fields?: EntityField[];
+}
+export interface GetEntityOutput {
+    id: EntityId;
+    type: EntityType;
+    title: string;
+    status: EntityStatus;
+    workstream: Workstream;
+    last_updated: string;
+    parent?: {
+        id: EntityId;
+        title: string;
+    };
+    children_count?: number;
+    content?: string;
+    priority?: Priority;
+    dependencies?: {
+        blocks: EntityId[];
+        blocked_by: EntityId[];
+    };
+    dependency_details?: {
+        blocks: EntitySummary[];
+        blocked_by: EntitySummary[];
+    };
+    task_progress?: {
+        total: number;
+        completed: number;
+    };
+    acceptance_criteria?: string[];
+    children?: EntitySummary[];
+    implementation_context?: {
+        required: EntitySummary[];
+        reference: EntitySummary[];
+        assumes: string[];
+    };
+    documents?: EntityId[];
+    documented_by?: EntityId[];
+    implemented_by?: EntityId[];
+    decided_by?: EntityId[];
+    test_refs?: string[];
+    user_story?: string;
+    tier?: string;
+    phase?: string;
+    /** Info about requested fields that don't apply to this entity type. Only included when non-empty. */
+    _field_info?: {
+        inapplicable: string[];
+    };
+}
+export interface GetEntitiesInput {
+    /** Array of entity IDs to retrieve */
+    ids: EntityId[];
+    /** Fields to include in response. If not specified, returns summary fields. */
+    fields?: EntityField[];
+}
+export interface GetEntitiesOutput {
+    /** Retrieved entities keyed by ID */
+    entities: Record<EntityId, GetEntityOutput>;
+    /** IDs that were not found */
+    not_found: EntityId[];
+}
+export type ManageDocumentsAction = 'get_decision_history' | 'supersede_document' | 'get_document_history' | 'check_freshness';
+export interface ManageDocumentsInput {
+    action: ManageDocumentsAction;
+    topic?: string;
+    workstream?: Workstream;
+    include_superseded?: boolean;
+    include_archived?: boolean;
+    document_id?: EntityId;
+    decision_id?: EntityId;
+    new_content?: string;
+    change_summary?: string;
+}
+export type ManageDocumentsOutput = {
+    action: 'get_decision_history';
+} & GetDecisionHistoryOutput | {
+    action: 'supersede_document';
+} & SupersedeDocumentOutput | {
+    action: 'get_document_history';
+} & GetDocumentHistoryOutput | {
+    action: 'check_freshness';
+} & CheckDocumentFreshnessOutput;
+export interface GetDecisionHistoryInput {
+    topic?: string;
+    workstream?: Workstream;
+    include_superseded?: boolean;
+    include_archived?: boolean;
+}
+export interface GetDecisionHistoryOutput {
+    decisions: Array<{
+        id: EntityId;
+        title: string;
+        status: string;
+        decided_on: string;
+        affects: EntityId[];
+        superseded_by?: EntityId;
+    }>;
+    decision_chains: Array<{
+        current: EntityId;
+        history: EntityId[];
+    }>;
+}
+export interface SupersedeDocumentInput {
+    document_id: EntityId;
+    decision_id: EntityId;
+    new_content: string;
+    change_summary: string;
+}
+export interface SupersedeDocumentOutput {
+    document_id: EntityId;
+    new_version: number;
+    decision_id: EntityId;
+    previous_version_ref: string;
+}
+export interface GetDocumentHistoryInput {
+    document_id: EntityId;
+}
+export interface GetDocumentHistoryOutput {
+    document_id: EntityId;
+    current_version: number;
+    history: Array<{
+        version: number;
+        date: string;
+        supersedes_decision?: EntityId;
+        change_summary: string;
+        git_ref?: string;
+    }>;
+}
+export interface CheckDocumentFreshnessInput {
+    document_id: EntityId;
+}
+export interface CheckDocumentFreshnessOutput {
+    document_id: EntityId;
+    is_fresh: boolean;
+    stale_reasons: Array<{
+        type: 'newer_decision' | 'referenced_doc_changed' | 'todo_items';
+        detail: string;
+        entity_id?: EntityId;
+    }>;
+    suggested_updates: string[];
+}
+export interface GetFeatureCoverageInput {
+    phase?: 'MVP' | '0' | '1' | '2' | '3' | '4' | '5';
+    tier?: 'OSS' | 'Premium';
+    include_tests?: boolean;
+    /** If true, return only summary without features array. Reduces response size significantly. */
+    summary_only?: boolean;
+    /** Filter to specific feature IDs. When specified, only these features are included. */
+    feature_ids?: EntityId[];
+    /** Fields to include in each feature. If not specified, returns all fields. */
+    fields?: ('id' | 'title' | 'tier' | 'phase' | 'status' | 'implementation' | 'documentation' | 'testing')[];
+}
+export interface FeatureCoverageItem {
+    id: EntityId;
+    title: string;
+    tier: 'OSS' | 'Premium';
+    phase: 'MVP' | '0' | '1' | '2' | '3' | '4' | '5';
+    status: 'Planned' | 'In Progress' | 'Complete' | 'Deferred';
+    implementation: {
+        milestones: EntityId[];
+        stories: EntityId[];
+        progress_percent: number;
+    };
+    documentation: {
+        specs: EntityId[];
+        guides: EntityId[];
+        coverage: 'full' | 'partial' | 'none';
+    };
+    testing?: {
+        test_refs: string[];
+        has_tests: boolean;
+    };
+}
+export interface GetFeatureCoverageOutput {
+    /** Feature coverage items. Omitted when summary_only is true. */
+    features?: FeatureCoverageItem[];
+    summary: {
+        total: number;
+        implemented: number;
+        documented: number;
+        tested: number;
+        gaps: {
+            missing_implementation: EntityId[];
+            missing_docs: EntityId[];
+            missing_tests: EntityId[];
+        };
+    };
+}
+export interface GetSchemaInput {
+    /** Entity type to get schema for. If not specified, returns all schemas. */
+    entity_type?: EntityType;
+    /** If true, only return relationship definitions */
+    relationships_only?: boolean;
+}
+export interface SchemaFieldDefinition {
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    values?: string[];
+    description?: string;
+    relationship?: {
+        target_types: string[];
+        inverse?: string;
+        auto_sync?: boolean;
+    };
+}
+export interface EntitySchema {
+    type: EntityType;
+    id_pattern: string;
+    fields: Record<string, SchemaFieldDefinition>;
+    statuses: string[];
+    status_transitions?: Record<string, string[]>;
+}
+export interface GetSchemaOutput {
+    schemas: EntitySchema[];
+}
+//# sourceMappingURL=tool-types.d.ts.map