argustack 0.2.0 → 0.3.1

package/dist/mcp/helpers.d.ts

@@ -1,5 +1,3 @@
-import { getEnabledSources } from '../workspace/config.js';
-import type { WorkspaceConfig, SourceType } from '../core/types/index.js';
 import type { ISourceProvider } from '../core/ports/source-provider.js';
 import type { IStorage } from '../core/ports/storage.js';
 import type { ICodeGraph } from '../core/ports/code-graph.js';
@@ -7,56 +5,149 @@ import type { ICodeVectorStore } from '../core/ports/code-vector-store.js';
 import type { ICodeParser } from '../core/ports/code-parser.js';
 import type { ICodeEmbedding } from '../core/ports/code-embedding.js';
 import type { ICodeMetaStore } from '../core/ports/code-meta.js';
+import type { IChatLlm } from '../core/ports/chat-llm.js';
+import type { IWorkspaceStore } from '../core/ports/workspace-store.js';
+import type { Workspace, WorkspaceConfig } from '../core/types/index.js';
 import type { ToolResponse } from './types.js';
+export interface WorkspaceContext {
+    readonly workspaceId: string;
+    readonly workspace: Workspace;
+    readonly config: WorkspaceConfig;
+}
 export type WorkspaceResult = {
     ok: true;
-    root: string;
+    workspaceId: string;
+    workspace: Workspace;
     config: WorkspaceConfig;
 } | {
     ok: false;
     reason: string;
 };
-export interface WorkspaceListItem {
-    name: string;
-    path: string;
-    sources: SourceType[];
-    active: boolean;
+interface CachedCodeAdapters {
+    graph: ICodeGraph;
+    vec: ICodeVectorStore;
+    parser: ICodeParser;
+    embedding: ICodeEmbedding;
+    meta: ICodeMetaStore;
+    storage: IStorage & ICodeMetaStore;
+    chatLlm: IChatLlm | null;
+    projectRoot: string;
 }
-export declare function loadWorkspace(): WorkspaceResult;
+export type CodeAdapters = Omit<CachedCodeAdapters, 'projectRoot'>;
+export declare function setActiveStorage(storage: IStorage): void;
+export declare function getActiveStorage(): IStorage | null;
+export declare function setActiveWorkspaceStore(store: IWorkspaceStore): void;
+export declare function getWorkspaceStore(): Promise<IWorkspaceStore>;
 /**
- * Switch to a different workspace by name.
- * Closes current storage connection, updates env, reloads .env.
+ * Resolve the workspace for a tool invocation.
+ *
+ * Resolution order (mirrors {@link import('../workspace/resolver').requireWorkspaceId}):
+ *   1. `explicit` (the tool's `workspace_id` schema field).
+ *   2. `ARGUSTACK_WORKSPACE_ID` env var.
+ *   3. `~/.argustack/active-workspace.json#activeWorkspaceId`.
+ *   4. Auto-pick when exactly one workspace exists in the hub.
+ *
+ * Returns a structured result so MCP tools can render a tool-friendly
+ * error response instead of throwing.
  */
-export declare function switchWorkspace(name: string): Promise<WorkspaceResult>;
+export declare function loadWorkspace(explicit?: string): Promise<WorkspaceResult>;
 /**
- * Scan parent directory for sibling workspaces.
+ * Switch the active workspace. Writes the hub `active-workspace.json`,
+ * touches `last_active_at`, and resets cached connections so subsequent
+ * tool calls reconnect with whatever per-workspace settings apply.
  */
-export declare function listSiblingWorkspaces(): WorkspaceListItem[];
-export declare function setActiveStorage(storage: IStorage): void;
-export declare function getActiveStorage(): IStorage | null;
-export declare function createAdapters(workspaceRoot: string): Promise<{
+export declare function switchWorkspace(name: string): Promise<WorkspaceResult>;
+export interface ResolvedAdapters {
     source: ISourceProvider | null;
     storage: IStorage;
-}>;
-export interface CodeAdapters {
-    graph: ICodeGraph;
-    vec: ICodeVectorStore;
-    parser: ICodeParser;
-    embedding: ICodeEmbedding;
-    meta: ICodeMetaStore;
-    storage: IStorage & ICodeMetaStore;
+    workspaceId: string;
 }
+/**
+ * Build the per-tool adapter set. The hub Postgres pool is reused
+ * across invocations via {@link activeStorage}; the source provider
+ * (Jira/proxy) is recreated each call since per-workspace project
+ * filters can change.
+ */
+export declare function createAdapters(workspaceId: string): Promise<ResolvedAdapters>;
 export declare function setActiveCodeAdapters(adapters: CodeAdapters | null): void;
 export declare function getActiveCodeAdapters(): CodeAdapters | null;
 /**
- * Build adapters needed by code-intelligence MCP tools.
- * Returns null if env is missing required vars (NEO4J_URI, QDRANT_URL,
- * VOYAGE_API_KEY). Caller must report the error to the user via errorResponse.
+ * Build adapters used by code-intelligence MCP tools for a specific
+ * workspace. Returns `null` if the hub config is missing the bits
+ * required by the chosen embedding provider.
  */
-export declare function createCodeAdapters(workspaceRoot: string): Promise<CodeAdapters | null>;
+export declare function createCodeAdapters(workspaceId: string): Promise<CodeAdapters | null>;
+/**
+ * Annotation presets reused across MCP tool registrations.
+ * Mirrors the `ToolAnnotations` shape from @modelcontextprotocol/sdk.
+ *
+ * - READ_ONLY    — pure query, no side effects, safe to retry.
+ * - LOCAL_WRITE  — mutates hub-local state (board.md / Postgres rows),
+ *                  no remote calls (e.g. create_issue with source='local').
+ * - REMOTE_WRITE — pushes to or pulls from external systems (Jira, GitHub).
+ *                  destructiveHint flips on so clients can warn the user
+ *                  before invocation.
+ */
+export declare const ANNOTATIONS: {
+    readonly READ_ONLY: {
+        readonly readOnlyHint: true;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+    };
+    readonly REMOTE_READ: {
+        readonly readOnlyHint: true;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+    readonly LOCAL_WRITE: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: false;
+        readonly openWorldHint: false;
+    };
+    readonly REMOTE_WRITE: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+        readonly idempotentHint: false;
+        readonly openWorldHint: true;
+    };
+};
 export declare function textResponse(text: string): ToolResponse;
 export declare function errorResponse(text: string): ToolResponse;
+/**
+ * Standard "workspace not found" error response for MCP tools.
+ *
+ * Wraps the technical {@link WorkspaceResult.reason} in a UX-friendly
+ * message that always contains the marker "Workspace not found" so
+ * clients and tests can detect it regardless of which underlying
+ * resolution step failed (no `.argustack/`, missing env var, unknown
+ * id, etc.).
+ */
+export declare function workspaceNotFoundResponse(reason: string): ToolResponse;
 export declare function getErrorMessage(err: unknown): string;
+/**
+ * High-level helper: resolve workspace, build adapters, run callback.
+ * Centralises the boilerplate for MCP tools that just need a scoped
+ * `storage` and `workspaceId`.
+ */
+export declare function withWorkspace<T>(explicit: string | undefined, fn: (ctx: {
+    storage: IStorage;
+    workspaceId: string;
+    workspace: Workspace;
+    config: WorkspaceConfig;
+}) => Promise<T>): Promise<T | ToolResponse>;
 export declare function str(value: unknown): string;
-export { getEnabledSources };
+/**
+ * Render `value` via {@link str}, but substitute `fallback` when the
+ * result is the empty string. Replaces the deprecated `str(x) || 'N/A'`
+ * pattern in a way that satisfies @typescript-eslint/strict-boolean-expressions.
+ */
+export declare function strOr(value: unknown, fallback: string): string;
+/**
+ * Render a possibly-null/undefined string with a fallback.
+ */
+export declare function nullableStr(value: string | null | undefined, fallback: string): string;
+/** True when `value` is a non-empty string. */
+export declare function hasText(value: string | null | undefined): value is string;
+export {};
 //# sourceMappingURL=helpers.d.ts.map

package/dist/mcp/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/mcp/helpers.ts"],"names":[],"mappings":"AAKA,OAAO,EAAc,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEvE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACnD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AA6DD,wBAAgB,aAAa,IAAI,eAAe,CAsD/C;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA6D5E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,iBAAiB,EAAE,CA0D3D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,CAExD;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,GAAG,IAAI,CAElD;AAED,wBAAsB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;IACnE,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC,CAkCD;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,gBAAgB,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,cAAc,CAAC;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,QAAQ,GAAG,cAAc,CAAC;CACpC;AAID,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAEzE;AAED,wBAAgB,qBAAqB,IAAI,YAAY,GAAG,IAAI,CAE3D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAuE5F;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAEvD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAExD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAKpD;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAc1C;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/mcp/helpers.ts"],"names":[],"mappings":"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"}