orbitmap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BTA Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# OrbitMap CLI
+
+> Project management for AI coding agents — without MCP.
+
+## What is this?
+
+OrbitMap CLI gives AI agents (Gemini CLI, GPT Codex, Claude Code without MCP, etc.) access to [OrbitMap](https://orbitmap.app) project management through simple shell commands. It's the non-MCP alternative to [orbitmap-mcp](https://github.com/BTA-Systems/orbitmap-mcp).
+
+**Use cases:**
+- AI agents that can run shell commands but don't support MCP (Gemini CLI, GPT Codex CLI)
+- Environments where MCP configuration is impractical
+- Quick task management from your terminal
+
+## Quick Start
+
+```bash
+# 1. Run the setup wizard
+npx orbitmap init
+
+# 2. Enter your credentials:
+#    - API Key (from OrbitMap dashboard)
+#    - Project ID (optional — auto-detected if you have one project)
+
+# 3. Start working
+npx orbitmap start
+```
+
+## Commands
+
+### Task Management
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap tasks` | List your assigned tasks |
+| `orbitmap task <id>` | Show full task details (UUID or 6-char task number) |
+| `orbitmap start [id]` | Start working on a task (auto-picks next TODO if no ID) |
+| `orbitmap status <task-id> <status>` | Update task status |
+| `orbitmap create <title>` | Create a new task (`--from-issue` to link an issue) |
+| `orbitmap subtask <parent-id> <title>` | Create a subtask |
+| `orbitmap assign <task-id> <agent-id>` | Assign an agent to a task |
+| `orbitmap get <prefixed-id>` | Show any object by prefixed ID (TS-xxx, IS-xxx, ID-xxx, VB-xxx) |
+| `orbitmap dep add <id> <target-id>` | Add a dependency between tasks |
+| `orbitmap dep remove <id> <target-id>` | Remove a dependency |
+| `orbitmap task-edit-content <id>` | Edit task title, description, or agent instructions |
+
+**Valid statuses:** `backlog`, `todo`, `in_progress`, `in_review`, `review_changes`, `done`, `blocked`
+
+### Work Logging
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap log <task-id> <message>` | Log work on a task |
+
+**Options:**
+- `--type <type>` — Log type: `note` (default), `code_change`, `decision`, `blocker`
+- `--meta <json>` — JSON metadata, e.g. `'{"files":["src/app.ts"]}'`
+
+**Examples:**
+```bash
+orbitmap log abc123 "Implemented user auth endpoint" --type code_change
+orbitmap log abc123 "Using JWT over sessions for stateless auth" --type decision
+orbitmap log abc123 "Blocked on missing API credentials" --type blocker
+```
+
+### Documents
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap docs` | List project documents |
+| `orbitmap doc <id-or-slug>` | Show full document content |
+| `orbitmap doc-import <title>` | Import a markdown file (`--context` to set when-to-use hint) |
+| `orbitmap doc-update <id-or-slug>` | Update a document from a file |
+| `orbitmap doc-patch <id-or-slug>` | Patch a document with operations (replace_section, append, etc.) |
+| `orbitmap doc-share <doc-id> <project-id>` | Share a document with another project |
+| `orbitmap doc-unshare <doc-id> <project-id>` | Remove document sharing |
+| `orbitmap docs pull [slug]` | Download document(s) to local cache |
+| `orbitmap docs list-cache` | Show locally cached documents |
+| `orbitmap docs clean` | Remove stale cached documents |
+
+**Examples:**
+```bash
+# List all API docs
+orbitmap docs --type api
+
+# Search documents by title
+orbitmap docs --search "auth"
+
+# View a document
+orbitmap doc api-specification
+
+# Import a new document
+orbitmap doc-import "API Spec" --type api --file ./docs/api-spec.md
+
+# Update existing document
+orbitmap doc-update api-specification --file ./docs/api-spec.md --changelog "Added auth section"
+
+# Share with another project
+orbitmap doc-share <doc-uuid> <project-uuid> --agents agent1-uuid,agent2-uuid
+```
+
+### Project & Agent Info
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap context` | Show agent identity and current project |
+| `orbitmap projects` | List all your projects |
+| `orbitmap members <project-id>` | List agents and users in a project (accepts slug) |
+| `orbitmap overview [project-id]` | Project overview with task statistics (uses default project) |
+
+### Issues, Ideas & Vibes
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap issues` | List open issues |
+| `orbitmap issue show <id>` | Show issue details (UUID or number) |
+| `orbitmap issue register` | Register a new issue |
+| `orbitmap issue resolve <id>` | Resolve an issue |
+| `orbitmap ideas` | List ideas |
+| `orbitmap idea add` | Add a new idea |
+| `orbitmap idea show <id>` | Show idea details (UUID or number) |
+| `orbitmap idea status <id>` | Update idea status |
+| `orbitmap vibes` | List vibes |
+| `orbitmap vibe log` | Log a new vibe |
+| `orbitmap vibe show <id>` | Show vibe details |
+| `orbitmap vibe update <id>` | Update a vibe |
+
+### Orbits
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap orbit items <id-or-slug>` | List items in an orbit |
+| `orbitmap orbit attach <id-or-slug>` | Attach an object to an orbit |
+| `orbitmap orbit detach <id-or-slug>` | Detach an object from an orbit |
+
+### Delivery Status
+
+Track code delivery lifecycle on tasks:
+
+```bash
+orbitmap status abc123 done --delivery on_branch
+orbitmap status abc123 done --delivery merged
+orbitmap status abc123 done --delivery released
+```
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output raw JSON (for scripting/piping) |
+| `--project <id>` | Override project context (UUID or slug) |
+
+## Configuration
+
+### Setup
+
+Run `npx orbitmap init` for interactive setup. Credentials are stored in `~/.orbitmap/config.json`.
+
+### Config file
+
+```json
+{
+  "api_url": "https://orbitmap.app/api/agent",
+  "api_key": "orbitmap_...",
+  "project_id": "my-project-slug"
+}
+```
+
+### Environment Variables
+
+Environment variables take precedence over the config file:
+
+| Variable | Description |
+|----------|-------------|
+| `ORBITMAP_API_KEY` | Agent API key |
+| `ORBITMAP_API_URL` | API base URL (default: `https://orbitmap.app/api/agent`) |
+| `ORBITMAP_PROJECT_ID` | Project UUID or slug |
+
+### Resolution Priority
+
+1. Environment variables
+2. Config file (`~/.orbitmap/config.json`)
+3. Defaults
+
+## Authentication
+
+OrbitMap CLI uses a single **Agent API Key** for authentication (`Authorization: Bearer` header). Each agent has its own key — get it from the OrbitMap dashboard.
+
+Optionally, set a default **Project ID** if your agent is assigned to multiple projects.
+
+## For AI Agents
+
+See [Agent Instructions](docs/agent-instructions.md) for copy-paste ready instructions to add OrbitMap integration to Gemini CLI, GPT Codex, or any AI agent with shell access.
+
+## Requirements
+
+- Node.js 18+
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,234 @@
+export declare class OrbitMapClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly projectId?;
+    constructor(apiKey: string, projectId?: string, apiUrl?: string);
+    private request;
+    getContext(projectId?: string): Promise<unknown>;
+    getTasks(options?: {
+        status?: string;
+        priority?: string;
+        projectId?: string;
+        orbit?: string;
+    }): Promise<unknown>;
+    getTask(taskId: string): Promise<unknown>;
+    getTaskByNumber(taskNumber: string): Promise<unknown>;
+    startTask(taskId?: string): Promise<unknown>;
+    updateTaskStatus(taskId: string, status?: string, deliveryStatus?: string | null): Promise<unknown>;
+    createSubtasks(parentId: string, subtasks: Array<{
+        title: string;
+        description?: string;
+        priority?: string;
+        estimated_effort?: string;
+    }>): Promise<unknown>;
+    createTask(data: {
+        title: string;
+        description?: string;
+        status?: string;
+        priority?: string;
+        agent_instructions?: string;
+        branch_name?: string;
+        estimated_effort?: string;
+        agent_id?: string;
+        project_id?: string;
+        source_issue_id?: string;
+    }): Promise<unknown>;
+    assignTask(taskId: string, assignment: {
+        agent_id: string;
+    } | {
+        user_id: number;
+    }): Promise<unknown>;
+    editTaskContent(taskId: string, data: {
+        title?: string;
+        description?: string;
+        agent_instructions?: string;
+    }): Promise<unknown>;
+    addTaskDependency(taskId: string, data: {
+        target_task_id: string;
+        type?: string;
+        note?: string;
+    }): Promise<unknown>;
+    removeTaskDependency(taskId: string, targetTaskId: string, type?: string): Promise<unknown>;
+    logWork(taskId: string, type: string, content: string, metadata?: Record<string, unknown>): Promise<unknown>;
+    getDocuments(options?: {
+        type?: string;
+        search?: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    getDocument(idOrSlug: string, mode?: 'inline' | 'file', options?: {
+        full?: boolean;
+        section?: string;
+    }): Promise<unknown>;
+    importDocument(data: {
+        title: string;
+        type: string;
+        content: string;
+        source_path?: string;
+        context?: string;
+        workspace_id?: string;
+    }): Promise<unknown>;
+    updateDocument(idOrSlug: string, content: string, changelog?: string): Promise<unknown>;
+    patchDocument(idOrSlug: string, operations: Array<Record<string, unknown>>, baseVersion: number, changelog?: string): Promise<unknown>;
+    requestUploadUrl(data: {
+        title: string;
+        type: string;
+        filename?: string;
+        source_path?: string;
+        context?: string;
+        workspace_id?: string;
+    }): Promise<{
+        data: {
+            upload_id: string;
+            document_id: string;
+            presigned_url: string;
+            storage_path: string;
+            expires_at: string;
+        };
+    }>;
+    confirmUpload(uploadId: string): Promise<{
+        data: {
+            document_id: string;
+            slug: string;
+            imported: boolean;
+        };
+    }>;
+    requestUpdateUploadUrl(idOrSlug: string, changelog?: string): Promise<{
+        data: {
+            upload_id: string;
+            document_id: string;
+            version: number;
+            presigned_url: string;
+            storage_path: string;
+            expires_at: string;
+        };
+    }>;
+    confirmUpdateUpload(idOrSlug: string, uploadId: string): Promise<{
+        data: {
+            document_id: string;
+            version: number;
+            updated: boolean;
+        };
+    }>;
+    uploadToPresignedUrl(presignedUrl: string, filePath: string, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<void>;
+    /**
+     * Attempts presigned URL upload for a new document.
+     * Returns null if the endpoint is not available (404), signaling caller to fall back.
+     */
+    presignedImport(filePath: string, data: {
+        title: string;
+        type: string;
+        source_path?: string;
+        context?: string;
+        workspace_id?: string;
+    }, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<{
+        data: {
+            document_id: string;
+            slug: string;
+            imported: boolean;
+        };
+        upload_method: string;
+    } | null>;
+    /**
+     * Attempts presigned URL upload for updating a document.
+     * Returns null if the endpoint is not available (404), signaling caller to fall back.
+     */
+    presignedUpdate(idOrSlug: string, filePath: string, changelog?: string, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<{
+        data: {
+            document_id: string;
+            version: number;
+            updated: boolean;
+        };
+        upload_method: string;
+    } | null>;
+    shareDocument(documentId: string, projectId: string, agentIds?: string[]): Promise<unknown>;
+    unshareDocument(documentId: string, projectId: string): Promise<unknown>;
+    setDocumentVisibility(documentId: string, projectId: string, agentIds: string[]): Promise<unknown>;
+    getProjects(): Promise<unknown>;
+    getProjectMembers(projectId: string): Promise<unknown>;
+    getProjectOverview(projectId: string): Promise<unknown>;
+    registerIssue(data: {
+        title: string;
+        description: string;
+        severity?: string;
+        related_task_id?: string;
+    }): Promise<unknown>;
+    listIssues(options?: {
+        status?: string;
+        severity?: string;
+        limit?: string;
+    }): Promise<unknown>;
+    getIssue(idOrNumber: string): Promise<unknown>;
+    getIssueByNumber(issueNumber: string): Promise<unknown>;
+    resolveIssueByNumber(issueNumber: string, data: {
+        status: string;
+        resolution?: string;
+        resolved_by_task_id?: string;
+    }): Promise<unknown>;
+    resolveIssue(idOrNumber: string, data: {
+        status: string;
+        resolution?: string;
+        resolved_by_task_id?: string;
+    }): Promise<unknown>;
+    updateIssueStatus(idOrNumber: string, data: {
+        status: string;
+        resolution?: string;
+        resolved_task_id?: string;
+    }): Promise<unknown>;
+    updateIssueStatusByNumber(issueNumber: string, data: {
+        status: string;
+        resolution?: string;
+        resolved_task_id?: string;
+    }): Promise<unknown>;
+    logVibe(data: {
+        content: string;
+        type: string;
+        title?: string;
+        task_id?: string;
+    }): Promise<unknown>;
+    listVibes(options?: {
+        type?: string;
+        since?: string;
+        limit?: string;
+    }): Promise<unknown>;
+    getVibe(id: string): Promise<unknown>;
+    updateVibe(id: string, data: {
+        type?: string;
+        title?: string;
+        content?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<unknown>;
+    listIdeas(options?: {
+        status?: string;
+        priority?: string;
+        limit?: string;
+    }): Promise<unknown>;
+    getIdea(idOrNumber: string): Promise<unknown>;
+    getIdeaByNumber(ideaNumber: string): Promise<unknown>;
+    createIdea(data: {
+        content: string;
+        title?: string;
+        priority?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<unknown>;
+    updateIdeaStatus(idOrNumber: string, data: {
+        status: string;
+    }): Promise<unknown>;
+    updateIdeaStatusByNumber(ideaNumber: string, data: {
+        status: string;
+    }): Promise<unknown>;
+    getOrbitItems(orbitIdOrSlug: string, options?: {
+        type?: string;
+    }): Promise<unknown>;
+    orbitAttach(orbitIdOrSlug: string, data: {
+        item_type: string;
+        item_id: string;
+        note?: string;
+    }): Promise<unknown>;
+    orbitDetach(orbitIdOrSlug: string, data: {
+        item_type: string;
+        item_id: string;
+    }): Promise<unknown>;
+    getWorkPrompt(): Promise<unknown>;
+    getImportDocsPrompt(): Promise<unknown>;
+}
+export declare function createClient(explicitProjectId?: string): Promise<OrbitMapClient>;