@happyvertical/projects 0.74.8

package/AGENT.md

@@ -0,0 +1,33 @@
+# @happyvertical/projects
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+Standardized project management interface for GitHub Projects, Jira, ZenHub, and Linear
+
+## Package Map
+- Package: `@happyvertical/projects`
+- Hierarchy path: `@happyvertical/sdk > packages > projects`
+- Workspace position: `21 of 30` local packages
+- Internal dependencies: `@happyvertical/graphql`, `@happyvertical/repos`
+- Internal dependents: `@happyvertical/github-actions`
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/projects build
+pnpm --filter @happyvertical/projects test
+pnpm --filter @happyvertical/projects clean
+```
+
+## Agent Correction Loops
+- If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/graphql build`, `pnpm --filter @happyvertical/repos build`) and then rerun `pnpm --filter @happyvertical/projects build`.
+- If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/projects clean` followed by `pnpm --filter @happyvertical/projects build` and `pnpm --filter @happyvertical/projects test`.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: Standardized project management interface for GitHub Projects, Jira, ZenHub, and Linear
+- Implements: none
+- Requires: @happyvertical/graphql, @happyvertical/repos
+- Stability: stable (Primary package surface is described as implemented and production-oriented.)
+<!-- END AGENT:GENERATED -->
+

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+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,352 @@
+# @happyvertical/projects
+
+Standardized project management interface for GitHub Projects, Jira, ZenHub, and Linear.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/projects @happyvertical/repos
+```
+
+## Claude Code Context
+
+Install Claude Code context files for AI-assisted development:
+
+```bash
+npx have-projects-context
+```
+
+This copies the package's `AGENT.md` documentation and `metadata.json` metadata to your project's `.claude/` directory, enabling Claude to provide better assistance when working with this package.
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { getProject } from '@happyvertical/projects';
+import { getRepository } from '@happyvertical/repos';
+
+// Get repository to retrieve issue node IDs
+const repo = await getRepository({
+  type: 'github',
+  owner: 'happyvertical',
+  repo: 'sdk',
+  token: process.env.GITHUB_TOKEN
+});
+
+// Get project with status field configuration
+const project = await getProject({
+  type: 'github',
+  projectId: 'PVT_kwDOB9Y8ns4A8-TY',
+  token: process.env.GITHUB_TOKEN,
+  statusFieldId: 'PVTSSF_lADOB9Y8ns4A8-TYzgw0GaY',
+  statusOptions: {
+    'New': 'option-id-1',
+    'Backlog': 'option-id-2',
+    'In Progress': 'option-id-3',
+    'Done': 'option-id-4'
+  }
+});
+
+// Add issue to project
+const issue = await repo.getIssue(352);
+const item = await project.addItem(issue.id);
+
+// Update status
+await project.updateItemStatus(item.id, 'In Progress');
+```
+
+### Kanban Workflow
+
+```typescript
+// List all items
+const items = await project.listItems();
+
+// Get available statuses
+const statuses = await project.listStatuses();
+
+// Move item through workflow
+await project.updateItemStatus(itemId, 'Ready');
+await project.updateItemStatus(itemId, 'In Progress');
+await project.updateItemStatus(itemId, 'Review');
+await project.updateItemStatus(itemId, 'Done');
+```
+
+### Custom Field Management
+
+```typescript
+// List all project fields
+const fields = await project.listFields();
+
+// Update custom field
+const priorityField = fields.find(f => f.name === 'Priority');
+if (priorityField) {
+  await project.updateItemField(itemId, priorityField.id, 'high-priority-option-id');
+}
+```
+
+## API Reference
+
+### Factory Function
+
+#### `getProject(options)`
+
+Creates a project management client instance.
+
+**Parameters:**
+- `options: ProjectConfig | IProject` - Project configuration or existing instance
+
+**Returns:** `Promise<IProject>`
+
+**Example:**
+```typescript
+const project = await getProject({
+  type: 'github',
+  projectId: 'PVT_kwDOB9Y8ns4A8-TY',
+  token: process.env.GITHUB_TOKEN,
+  statusFieldId: 'PVTSSF_lADOB9Y8ns4A8-TYzgw0GaY',
+  statusOptions: {
+    'New': 'option-id-1',
+    'Backlog': 'option-id-2',
+    'In Progress': 'option-id-3',
+    'Done': 'option-id-4'
+  }
+});
+```
+
+### IProject Interface
+
+#### Project Information
+
+##### `getProject(): Promise<Project>`
+
+Get project details including fields and statuses.
+
+**Returns:** Project metadata with all fields and status options
+
+#### Item Management
+
+##### `addItem(contentId: string): Promise<ProjectItem>`
+
+Add an issue or pull request to the project.
+
+**Parameters:**
+- `contentId: string` - Node ID of the issue or PR (from @happyvertical/repos)
+
+**Returns:** Created project item
+
+##### `removeItem(itemId: string): Promise<void>`
+
+Remove an item from the project.
+
+**Parameters:**
+- `itemId: string` - Project item ID
+
+##### `getItem(itemId: string): Promise<ProjectItem | null>`
+
+Get a specific project item.
+
+**Parameters:**
+- `itemId: string` - Project item ID
+
+**Returns:** Project item or null if not found
+
+##### `listItems(filters?: ItemFilters): Promise<ProjectItem[]>`
+
+List all items in the project.
+
+**Parameters:**
+- `filters?: ItemFilters` - Optional filters (limit, cursor, status)
+
+**Returns:** Array of project items
+
+#### Status Management
+
+##### `updateItemStatus(itemId: string, status: string): Promise<void>`
+
+Update the status of a project item.
+
+**Parameters:**
+- `itemId: string` - Project item ID
+- `status: string` - Status name (must match statusOptions in config)
+
+**Example:**
+```typescript
+await project.updateItemStatus(itemId, 'In Progress');
+```
+
+##### `listStatuses(): Promise<Status[]>`
+
+Get all available status options.
+
+**Returns:** Array of status definitions with IDs, names, colors
+
+#### Field Management
+
+##### `updateItemField(itemId: string, fieldId: string, value: unknown): Promise<void>`
+
+Update a custom field value.
+
+**Parameters:**
+- `itemId: string` - Project item ID
+- `fieldId: string` - Field ID
+- `value: unknown` - Field value (type depends on field type)
+
+##### `listFields(): Promise<Field[]>`
+
+Get all project fields.
+
+**Returns:** Array of field definitions
+
+## GitHub Projects V2 Setup
+
+### Finding Your Project ID
+
+1. Navigate to your GitHub Project
+2. In the URL, find the project number: `https://github.com/orgs/ORG/projects/123`
+3. Use GitHub CLI to get the node ID:
+   ```bash
+   gh api graphql -f query='
+     query {
+       organization(login: "ORG") {
+         projectV2(number: 123) {
+           id
+         }
+       }
+     }
+   '
+   ```
+
+### Finding Status Field ID and Options
+
+```bash
+gh api graphql -f query='
+  query {
+    node(id: "PVT_kwDOB9Y8ns4A8-TY") {
+      ... on ProjectV2 {
+        fields(first: 20) {
+          nodes {
+            ... on ProjectV2SingleSelectField {
+              id
+              name
+              options {
+                id
+                name
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+'
+```
+
+Look for the "Status" field and note:
+- Field ID (`PVTSSF_...`)
+- Option IDs for each status
+
+### Configuration Example
+
+```typescript
+const project = await getProject({
+  type: 'github',
+  projectId: 'PVT_kwDOB9Y8ns4A8-TY',      // From step 1
+  token: process.env.GITHUB_TOKEN,
+  statusFieldId: 'PVTSSF_lADOB9Y8ns4A8-TYzgw0GaY',  // From step 2
+  statusOptions: {
+    'New': '47fc9ee4',           // Option IDs from step 2
+    'Backlog': '4c6e9e0c',
+    'Planning': 'f75ad846',
+    'Ready': '98236657',
+    'In Progress': 'b5f9e3e1',
+    'Review': '5e1b3e8f',
+    'Done': '3f4e5d6c'
+  }
+});
+```
+
+## Standard Kanban Statuses
+
+The package exports standard kanban status names:
+
+```typescript
+import { KANBAN_STATUSES } from '@happyvertical/projects';
+
+// ['New', 'Backlog', 'Planning', 'Ready', 'In Progress', 'Review', 'Done']
+```
+
+## Error Handling
+
+```typescript
+import { ProjectError, ProjectErrorCode } from '@happyvertical/projects';
+
+try {
+  await project.updateItemStatus(itemId, 'Invalid Status');
+} catch (error) {
+  if (error instanceof ProjectError) {
+    switch (error.code) {
+      case ProjectErrorCode.INVALID_STATUS:
+        console.error('Status not found:', error.message);
+        break;
+      case ProjectErrorCode.UNAUTHORIZED:
+        console.error('Token lacks permissions');
+        break;
+      case ProjectErrorCode.RATE_LIMITED:
+        console.error('Rate limited, retry after delay');
+        break;
+    }
+  }
+}
+```
+
+## Integration with @happyvertical/repos
+
+Projects work seamlessly with repositories:
+
+```typescript
+import { getRepository } from '@happyvertical/repos';
+import { getProject } from '@happyvertical/projects';
+
+const repo = await getRepository({
+  type: 'github',
+  owner: 'happyvertical',
+  repo: 'sdk',
+  token: process.env.GITHUB_TOKEN
+});
+
+const project = await getProject({
+  type: 'github',
+  projectId: 'PVT_kwDOB9Y8ns4A8-TY',
+  token: process.env.GITHUB_TOKEN,
+  statusFieldId: 'PVTSSF_lADOB9Y8ns4A8-TYzgw0GaY',
+  statusOptions: {
+    'New': 'option-id-1',
+    'In Progress': 'option-id-2',
+    'Done': 'option-id-3'
+  }
+});
+
+// Create issue and add to project
+const issue = await repo.createIssue({
+  title: 'New feature',
+  body: 'Description',
+  labels: ['type: feature']
+});
+
+const item = await project.addItem(issue.id);
+await project.updateItemStatus(item.id, 'In Progress');
+```
+
+## Supported Platforms
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| GitHub Projects V2 | ✅ Complete | Full GraphQL implementation |
+| Jira | 🚧 Planned | Coming soon |
+| ZenHub | 🚧 Planned | Coming soon |
+| Linear | 🚧 Planned | Coming soon |
+
+## License
+
+MIT

package/dist/claude-context.d.ts

@@ -0,0 +1 @@
+export { }

package/dist/cli/claude-context.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=claude-context.d.ts.map

package/dist/cli/claude-context.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const Dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(Dirname, "../..");
+const targetDir = join(process.cwd(), ".claude");
+if (!existsSync(targetDir)) {
+  mkdirSync(targetDir, { recursive: true });
+}
+const pkgName = "projects";
+const agentMdSrc = existsSync(join(pkgRoot, "AGENT.md")) ? join(pkgRoot, "AGENT.md") : join(pkgRoot, "CLAUDE.md");
+const metaSrc = existsSync(join(pkgRoot, "metadata.json")) ? join(pkgRoot, "metadata.json") : join(pkgRoot, ".claude-meta.json");
+if (existsSync(agentMdSrc)) {
+  copyFileSync(agentMdSrc, join(targetDir, `have-${pkgName}.md`));
+}
+if (existsSync(metaSrc)) {
+  copyFileSync(metaSrc, join(targetDir, `have-${pkgName}.meta.json`));
+}
+console.log(`✓ Installed @happyvertical/${pkgName} context to .claude/`);
+//# sourceMappingURL=claude-context.js.map

package/dist/cli/claude-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-context.js","sources":["../../src/cli/claude-context.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * CLI script to install agent context for @happyvertical/projects\n * Run the published context installer binary for this package.\n */\nimport { copyFileSync, existsSync, mkdirSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst Dirname = dirname(fileURLToPath(import.meta.url));\nconst pkgRoot = join(Dirname, '../..');\nconst targetDir = join(process.cwd(), '.claude');\n\nif (!existsSync(targetDir)) {\n  mkdirSync(targetDir, { recursive: true });\n}\n\nconst pkgName = 'projects';\nconst agentMdSrc = existsSync(join(pkgRoot, 'AGENT.md'))\n  ? join(pkgRoot, 'AGENT.md')\n  : join(pkgRoot, 'CLAUDE.md');\nconst metaSrc = existsSync(join(pkgRoot, 'metadata.json'))\n  ? join(pkgRoot, 'metadata.json')\n  : join(pkgRoot, '.claude-meta.json');\n\nif (existsSync(agentMdSrc)) {\n  copyFileSync(agentMdSrc, join(targetDir, `have-${pkgName}.md`));\n}\n\nif (existsSync(metaSrc)) {\n  copyFileSync(metaSrc, join(targetDir, `have-${pkgName}.meta.json`));\n}\n\nconsole.log(`✓ Installed @happyvertical/${pkgName} context to .claude/`);\n"],"names":[],"mappings":";;;;AASA,MAAM,UAAU,QAAQ,cAAc,YAAY,GAAG,CAAC;AACtD,MAAM,UAAU,KAAK,SAAS,OAAO;AACrC,MAAM,YAAY,KAAK,QAAQ,IAAA,GAAO,SAAS;AAE/C,IAAI,CAAC,WAAW,SAAS,GAAG;AAC1B,YAAU,WAAW,EAAE,WAAW,KAAA,CAAM;AAC1C;AAEA,MAAM,UAAU;AAChB,MAAM,aAAa,WAAW,KAAK,SAAS,UAAU,CAAC,IACnD,KAAK,SAAS,UAAU,IACxB,KAAK,SAAS,WAAW;AAC7B,MAAM,UAAU,WAAW,KAAK,SAAS,eAAe,CAAC,IACrD,KAAK,SAAS,eAAe,IAC7B,KAAK,SAAS,mBAAmB;AAErC,IAAI,WAAW,UAAU,GAAG;AAC1B,eAAa,YAAY,KAAK,WAAW,QAAQ,OAAO,KAAK,CAAC;AAChE;AAEA,IAAI,WAAW,OAAO,GAAG;AACvB,eAAa,SAAS,KAAK,WAAW,QAAQ,OAAO,YAAY,CAAC;AACpE;AAEA,QAAQ,IAAI,8BAA8B,OAAO,sBAAsB;"}

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+export declare interface Field {
+    id: string;
+    name: string;
+    type: 'text' | 'number' | 'date' | 'single_select' | 'iteration';
+    options?: FieldOption[];
+}
+
+export declare interface FieldOption {
+    id: string;
+    name: string;
+    description?: string;
+    color?: string;
+}
+
+/**
+ * Get a project management client instance
+ *
+ * This is the main entry point following the pattern from @happyvertical/files and @happyvertical/sql.
+ * It can accept either a configuration object or an existing project instance.
+ *
+ * @param options - Project configuration or existing project instance
+ * @returns Promise resolving to project interface
+ *
+ * @example
+ * ```typescript
+ * import { getProject } from '@happyvertical/projects';
+ *
+ * // Create a GitHub Projects client
+ * const project = await getProject({
+ *   type: 'github',
+ *   owner: 'happyvertical',
+ *   projectId: 'PVT_kwDOB9Y8ns4A8-TY',
+ *   token: process.env.GITHUB_TOKEN,
+ *   statusFieldId: 'PVTSSF_lADOB9Y8ns4A8-TYzgw0GaY',
+ *   statusOptions: {
+ *     'New': 'option-id-1',
+ *     'Backlog': 'option-id-2',
+ *     'In Progress': 'option-id-3',
+ *     'Done': 'option-id-4'
+ *   }
+ * });
+ *
+ * // Use the client
+ * await project.addItem(issueNodeId);
+ * await project.updateItemStatus(itemId, 'In Progress');
+ *
+ * // Pass existing instance (returns it unchanged)
+ * const sameProject = await getProject(project);
+ * ```
+ */
+export declare function getProject(options: ProjectConfig | IProject): Promise<IProject>;
+
+/**
+ * GitHub Projects V2 implementation
+ */
+export declare class GitHubProject implements IProject {
+    private graphql;
+    private projectId;
+    private owner?;
+    private repo?;
+    private statusFieldId?;
+    private statusOptions?;
+    constructor(config: ProjectConfig);
+    getProject(): Promise<Project>;
+    addItem(contentId: string): Promise<ProjectItem>;
+    removeItem(itemId: string): Promise<void>;
+    getItem(itemId: string): Promise<ProjectItem | null>;
+    listItems(filters?: ItemFilters): Promise<ProjectItem[]>;
+    updateItemStatus(itemId: string, status: string): Promise<void>;
+    listStatuses(): Promise<Status[]>;
+    updateItemField(itemId: string, fieldId: string, value: unknown): Promise<void>;
+    listFields(): Promise<Field[]>;
+    /**
+     * Map GitHub field type to our standard types
+     */
+    private mapFieldType;
+}
+
+/**
+ * Project interface - all project implementations must implement this
+ */
+export declare interface IProject {
+    getProject(): Promise<Project>;
+    addItem(contentId: string): Promise<ProjectItem>;
+    removeItem(itemId: string): Promise<void>;
+    getItem(itemId: string): Promise<ProjectItem | null>;
+    listItems(filters?: ItemFilters): Promise<ProjectItem[]>;
+    updateItemStatus(itemId: string, status: string): Promise<void>;
+    listStatuses(): Promise<Status[]>;
+    updateItemField(itemId: string, fieldId: string, value: unknown): Promise<void>;
+    listFields(): Promise<Field[]>;
+}
+
+export declare interface ItemFilters {
+    status?: string;
+    assignees?: string[];
+    labels?: string[];
+    limit?: number;
+    cursor?: string;
+}
+
+/**
+ * Kanban status names for 6-lane structure
+ */
+export declare const KANBAN_STATUSES: readonly ["New", "Backlog", "Planning", "Ready", "In Progress", "Review", "Done"];
+
+export declare type KanbanStatus = (typeof KANBAN_STATUSES)[number];
+
+/**
+ * Core types for project management operations
+ */
+export declare interface Project {
+    id: string;
+    title: string;
+    description?: string;
+    owner: string;
+    url: string;
+    statuses: Status[];
+    fields: Field[];
+}
+
+/**
+ * Project configuration
+ */
+export declare interface ProjectConfig {
+    type: 'github' | 'jira' | 'zenhub' | 'linear';
+    projectId: string;
+    token: string;
+    owner?: string;
+    repo?: string;
+    statusFieldId?: string;
+    statusOptions?: Record<string, string>;
+    boardId?: string;
+    teamId?: string;
+}
+
+export declare class ProjectError extends Error {
+    code: ProjectErrorCode;
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, code: ProjectErrorCode, statusCode?: number | undefined, response?: unknown | undefined);
+    static fromHTTPStatus(statusCode: number, message: string, response?: unknown): ProjectError;
+    static networkError(message: string, cause?: Error): ProjectError;
+    isRetryable(): boolean;
+}
+
+/**
+ * Project error handling
+ */
+export declare enum ProjectErrorCode {
+    NOT_FOUND = "NOT_FOUND",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    INVALID_STATUS = "INVALID_STATUS",
+    INVALID_FIELD = "INVALID_FIELD",
+    ITEM_NOT_IN_PROJECT = "ITEM_NOT_IN_PROJECT",
+    RATE_LIMITED = "RATE_LIMITED",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    UNKNOWN = "UNKNOWN"
+}
+
+export declare interface ProjectItem {
+    id: string;
+    contentId: string;
+    status?: string;
+    fields: Record<string, unknown>;
+    type: 'Issue' | 'PullRequest' | 'DraftIssue';
+}
+
+export declare interface Status {
+    id: string;
+    name: string;
+    description?: string;
+    color?: string;
+    order: number;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,409 @@
+import { GraphQLClient } from "@happyvertical/graphql";
+var ProjectErrorCode = /* @__PURE__ */ ((ProjectErrorCode2) => {
+  ProjectErrorCode2["NOT_FOUND"] = "NOT_FOUND";
+  ProjectErrorCode2["UNAUTHORIZED"] = "UNAUTHORIZED";
+  ProjectErrorCode2["INVALID_STATUS"] = "INVALID_STATUS";
+  ProjectErrorCode2["INVALID_FIELD"] = "INVALID_FIELD";
+  ProjectErrorCode2["ITEM_NOT_IN_PROJECT"] = "ITEM_NOT_IN_PROJECT";
+  ProjectErrorCode2["RATE_LIMITED"] = "RATE_LIMITED";
+  ProjectErrorCode2["NETWORK_ERROR"] = "NETWORK_ERROR";
+  ProjectErrorCode2["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+  ProjectErrorCode2["UNKNOWN"] = "UNKNOWN";
+  return ProjectErrorCode2;
+})(ProjectErrorCode || {});
+class ProjectError extends Error {
+  constructor(message, code, statusCode, response) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "ProjectError";
+    Error.captureStackTrace(this, this.constructor);
+  }
+  static fromHTTPStatus(statusCode, message, response) {
+    let code;
+    switch (statusCode) {
+      case 404:
+        code = "NOT_FOUND";
+        break;
+      case 401:
+        code = "UNAUTHORIZED";
+        break;
+      case 403:
+        code = "UNAUTHORIZED";
+        break;
+      case 429:
+        code = "RATE_LIMITED";
+        break;
+      case 422:
+        code = "VALIDATION_ERROR";
+        break;
+      default:
+        code = "UNKNOWN";
+    }
+    return new ProjectError(message, code, statusCode, response);
+  }
+  static networkError(message, cause) {
+    return new ProjectError(
+      message,
+      "NETWORK_ERROR",
+      void 0,
+      cause
+    );
+  }
+  isRetryable() {
+    return this.code === "RATE_LIMITED" || this.code === "NETWORK_ERROR";
+  }
+}
+function isProjectInstance(value) {
+  return value !== null && typeof value === "object" && "getProject" in value && "addItem" in value && "updateItemStatus" in value && typeof value.getProject === "function";
+}
+async function getProject(options) {
+  if (isProjectInstance(options)) {
+    return options;
+  }
+  if (!options.type) {
+    throw new ProjectError(
+      "Project type is required",
+      ProjectErrorCode.VALIDATION_ERROR
+    );
+  }
+  if (!options.projectId) {
+    throw new ProjectError(
+      "Project ID is required",
+      ProjectErrorCode.VALIDATION_ERROR
+    );
+  }
+  if (!options.token) {
+    throw new ProjectError(
+      "Authentication token is required",
+      ProjectErrorCode.UNAUTHORIZED
+    );
+  }
+  switch (options.type) {
+    case "github": {
+      const { GitHubProject: GitHubProject2 } = await Promise.resolve().then(() => index);
+      return new GitHubProject2(options);
+    }
+    case "jira":
+      throw new ProjectError(
+        "Jira support not yet implemented",
+        ProjectErrorCode.UNKNOWN
+      );
+    case "zenhub":
+      throw new ProjectError(
+        "ZenHub support not yet implemented",
+        ProjectErrorCode.UNKNOWN
+      );
+    case "linear":
+      throw new ProjectError(
+        "Linear support not yet implemented",
+        ProjectErrorCode.UNKNOWN
+      );
+    default:
+      throw new ProjectError(
+        `Unsupported project type: ${options.type}`,
+        ProjectErrorCode.VALIDATION_ERROR
+      );
+  }
+}
+class GitHubProject {
+  graphql;
+  projectId;
+  owner;
+  repo;
+  statusFieldId;
+  statusOptions;
+  constructor(config) {
+    if (config.type !== "github") {
+      throw new Error("Invalid config type for GitHubProject");
+    }
+    this.graphql = new GraphQLClient({
+      endpoint: "https://api.github.com/graphql",
+      token: config.token
+    });
+    this.projectId = config.projectId;
+    this.owner = config.owner;
+    this.repo = config.repo;
+    this.statusFieldId = config.statusFieldId;
+    this.statusOptions = config.statusOptions;
+  }
+  // Project Info
+  async getProject() {
+    const query = `
+      query($projectId: ID!) {
+        node(id: $projectId) {
+          ... on ProjectV2 {
+            id
+            title
+            shortDescription
+            url
+            owner {
+              ... on Organization {
+                login
+              }
+              ... on User {
+                login
+              }
+            }
+            fields(first: 20) {
+              nodes {
+                ... on ProjectV2Field {
+                  id
+                  name
+                  dataType
+                }
+                ... on ProjectV2SingleSelectField {
+                  id
+                  name
+                  dataType
+                  options {
+                    id
+                    name
+                    description
+                    color
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    `;
+    const data = await this.graphql.query(query, {
+      projectId: this.projectId
+    });
+    const statusField = data.node.fields.nodes.find(
+      (f) => f.name === "Status" && f.options
+    );
+    return {
+      id: data.node.id,
+      title: data.node.title,
+      description: data.node.shortDescription,
+      owner: data.node.owner.login,
+      url: data.node.url,
+      statuses: statusField?.options ? statusField.options.map((opt, index2) => ({
+        id: opt.id,
+        name: opt.name,
+        description: opt.description,
+        color: opt.color,
+        order: index2
+      })) : [],
+      fields: data.node.fields.nodes.map((f) => ({
+        id: f.id,
+        name: f.name,
+        type: this.mapFieldType(f.dataType),
+        options: f.options?.map((opt) => ({
+          id: opt.id,
+          name: opt.name,
+          description: opt.description,
+          color: opt.color
+        }))
+      }))
+    };
+  }
+  // Items
+  async addItem(contentId) {
+    const mutation = `
+      mutation($projectId: ID!, $contentId: ID!) {
+        addProjectV2ItemById(input: {
+          projectId: $projectId
+          contentId: $contentId
+        }) {
+          item {
+            id
+            content {
+              ... on Issue {
+                id
+              }
+              ... on PullRequest {
+                id
+              }
+            }
+          }
+        }
+      }
+    `;
+    const data = await this.graphql.mutate(mutation, {
+      projectId: this.projectId,
+      contentId
+    });
+    return {
+      id: data.addProjectV2ItemById.item.id,
+      contentId: data.addProjectV2ItemById.item.content.id,
+      fields: {},
+      type: "Issue"
+    };
+  }
+  async removeItem(itemId) {
+    const mutation = `
+      mutation($projectId: ID!, $itemId: ID!) {
+        deleteProjectV2Item(input: {
+          projectId: $projectId
+          itemId: $itemId
+        }) {
+          deletedItemId
+        }
+      }
+    `;
+    await this.graphql.mutate(mutation, {
+      projectId: this.projectId,
+      itemId
+    });
+  }
+  async getItem(itemId) {
+    const query = `
+      query($itemId: ID!) {
+        node(id: $itemId) {
+          ... on ProjectV2Item {
+            id
+            content {
+              ... on Issue {
+                id
+              }
+              ... on PullRequest {
+                id
+              }
+            }
+          }
+        }
+      }
+    `;
+    const data = await this.graphql.query(query, { itemId });
+    if (!data.node) {
+      return null;
+    }
+    return {
+      id: data.node.id,
+      contentId: data.node.content.id,
+      fields: {},
+      type: "Issue"
+    };
+  }
+  async listItems(filters) {
+    const query = `
+      query($projectId: ID!, $first: Int!, $after: String) {
+        node(id: $projectId) {
+          ... on ProjectV2 {
+            items(first: $first, after: $after) {
+              nodes {
+                id
+                content {
+                  ... on Issue {
+                    id
+                  }
+                  ... on PullRequest {
+                    id
+                  }
+                }
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        }
+      }
+    `;
+    const data = await this.graphql.query(query, {
+      projectId: this.projectId,
+      first: filters?.limit || 100,
+      after: filters?.cursor
+    });
+    return data.node.items.nodes.map((item) => ({
+      id: item.id,
+      contentId: item.content.id,
+      fields: {},
+      type: "Issue"
+    }));
+  }
+  // Status Management
+  async updateItemStatus(itemId, status) {
+    if (!this.statusFieldId || !this.statusOptions) {
+      throw new ProjectError(
+        "Status field configuration is required. Provide statusFieldId and statusOptions in config.",
+        ProjectErrorCode.INVALID_STATUS
+      );
+    }
+    const statusOptionId = this.statusOptions[status];
+    if (!statusOptionId) {
+      throw new ProjectError(
+        `Status "${status}" not found in project configuration. Available: ${Object.keys(this.statusOptions).join(", ")}`,
+        ProjectErrorCode.INVALID_STATUS
+      );
+    }
+    await this.updateItemField(itemId, this.statusFieldId, statusOptionId);
+  }
+  async listStatuses() {
+    const project = await this.getProject();
+    return project.statuses;
+  }
+  // Field Management
+  async updateItemField(itemId, fieldId, value) {
+    const mutation = `
+      mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $value: ProjectV2FieldValue!) {
+        updateProjectV2ItemFieldValue(input: {
+          projectId: $projectId
+          itemId: $itemId
+          fieldId: $fieldId
+          value: $value
+        }) {
+          projectV2Item {
+            id
+          }
+        }
+      }
+    `;
+    await this.graphql.mutate(mutation, {
+      projectId: this.projectId,
+      itemId,
+      fieldId,
+      value: { singleSelectOptionId: value }
+    });
+  }
+  async listFields() {
+    const project = await this.getProject();
+    return project.fields;
+  }
+  /**
+   * Map GitHub field type to our standard types
+   */
+  mapFieldType(dataType) {
+    switch (dataType.toLowerCase()) {
+      case "text":
+        return "text";
+      case "number":
+        return "number";
+      case "date":
+        return "date";
+      case "single_select":
+        return "single_select";
+      case "iteration":
+        return "iteration";
+      default:
+        return "text";
+    }
+  }
+}
+const index = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  GitHubProject
+}, Symbol.toStringTag, { value: "Module" }));
+const KANBAN_STATUSES = [
+  "New",
+  "Backlog",
+  "Planning",
+  "Ready",
+  "In Progress",
+  "Review",
+  "Done"
+];
+export {
+  GitHubProject,
+  KANBAN_STATUSES,
+  ProjectError,
+  ProjectErrorCode,
+  getProject
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/errors.ts","../src/factory.ts","../src/github/index.ts","../src/types.ts"],"sourcesContent":["/**\n * Project error handling\n */\n\nexport enum ProjectErrorCode {\n  NOT_FOUND = 'NOT_FOUND',\n  UNAUTHORIZED = 'UNAUTHORIZED',\n  INVALID_STATUS = 'INVALID_STATUS',\n  INVALID_FIELD = 'INVALID_FIELD',\n  ITEM_NOT_IN_PROJECT = 'ITEM_NOT_IN_PROJECT',\n  RATE_LIMITED = 'RATE_LIMITED',\n  NETWORK_ERROR = 'NETWORK_ERROR',\n  VALIDATION_ERROR = 'VALIDATION_ERROR',\n  UNKNOWN = 'UNKNOWN',\n}\n\nexport class ProjectError extends Error {\n  constructor(\n    message: string,\n    public code: ProjectErrorCode,\n    public statusCode?: number,\n    public response?: unknown,\n  ) {\n    super(message);\n    this.name = 'ProjectError';\n    Error.captureStackTrace(this, this.constructor);\n  }\n\n  static fromHTTPStatus(\n    statusCode: number,\n    message: string,\n    response?: unknown,\n  ): ProjectError {\n    let code: ProjectErrorCode;\n\n    switch (statusCode) {\n      case 404:\n        code = ProjectErrorCode.NOT_FOUND;\n        break;\n      case 401:\n        code = ProjectErrorCode.UNAUTHORIZED;\n        break;\n      case 403:\n        code = ProjectErrorCode.UNAUTHORIZED;\n        break;\n      case 429:\n        code = ProjectErrorCode.RATE_LIMITED;\n        break;\n      case 422:\n        code = ProjectErrorCode.VALIDATION_ERROR;\n        break;\n      default:\n        code = ProjectErrorCode.UNKNOWN;\n    }\n\n    return new ProjectError(message, code, statusCode, response);\n  }\n\n  static networkError(message: string, cause?: Error): ProjectError {\n    return new ProjectError(\n      message,\n      ProjectErrorCode.NETWORK_ERROR,\n      undefined,\n      cause,\n    );\n  }\n\n  isRetryable(): boolean {\n    return (\n      this.code === ProjectErrorCode.RATE_LIMITED ||\n      this.code === ProjectErrorCode.NETWORK_ERROR\n    );\n  }\n}\n","/**\n * Project factory function\n *\n * Creates project instances following the pattern from @happyvertical/files and @happyvertical/sql\n */\n\nimport { ProjectError, ProjectErrorCode } from './errors.js';\nimport type { IProject, ProjectConfig } from './types.js';\n\n/**\n * Check if value is already a project instance\n */\nfunction isProjectInstance(value: unknown): value is IProject {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'getProject' in value &&\n    'addItem' in value &&\n    'updateItemStatus' in value &&\n    typeof (value as IProject).getProject === 'function'\n  );\n}\n\n/**\n * Get a project management client instance\n *\n * This is the main entry point following the pattern from @happyvertical/files and @happyvertical/sql.\n * It can accept either a configuration object or an existing project instance.\n *\n * @param options - Project configuration or existing project instance\n * @returns Promise resolving to project interface\n *\n * @example\n * ```typescript\n * import { getProject } from '@happyvertical/projects';\n *\n * // Create a GitHub Projects client\n * const project = await getProject({\n *   type: 'github',\n *   owner: 'happyvertical',\n *   projectId: 'PVT_kwDOB9Y8ns4A8-TY',\n *   token: process.env.GITHUB_TOKEN,\n *   statusFieldId: 'PVTSSF_lADOB9Y8ns4A8-TYzgw0GaY',\n *   statusOptions: {\n *     'New': 'option-id-1',\n *     'Backlog': 'option-id-2',\n *     'In Progress': 'option-id-3',\n *     'Done': 'option-id-4'\n *   }\n * });\n *\n * // Use the client\n * await project.addItem(issueNodeId);\n * await project.updateItemStatus(itemId, 'In Progress');\n *\n * // Pass existing instance (returns it unchanged)\n * const sameProject = await getProject(project);\n * ```\n */\nexport async function getProject(\n  options: ProjectConfig | IProject,\n): Promise<IProject> {\n  // If already a project instance, return it\n  if (isProjectInstance(options)) {\n    return options;\n  }\n\n  // Validate configuration\n  if (!options.type) {\n    throw new ProjectError(\n      'Project type is required',\n      ProjectErrorCode.VALIDATION_ERROR,\n    );\n  }\n\n  if (!options.projectId) {\n    throw new ProjectError(\n      'Project ID is required',\n      ProjectErrorCode.VALIDATION_ERROR,\n    );\n  }\n\n  if (!options.token) {\n    throw new ProjectError(\n      'Authentication token is required',\n      ProjectErrorCode.UNAUTHORIZED,\n    );\n  }\n\n  // Create project instance based on type\n  switch (options.type) {\n    case 'github': {\n      const { GitHubProject } = await import('./github/index.js');\n      return new GitHubProject(options);\n    }\n\n    case 'jira':\n      throw new ProjectError(\n        'Jira support not yet implemented',\n        ProjectErrorCode.UNKNOWN,\n      );\n\n    case 'zenhub':\n      throw new ProjectError(\n        'ZenHub support not yet implemented',\n        ProjectErrorCode.UNKNOWN,\n      );\n\n    case 'linear':\n      throw new ProjectError(\n        'Linear support not yet implemented',\n        ProjectErrorCode.UNKNOWN,\n      );\n\n    default:\n      throw new ProjectError(\n        `Unsupported project type: ${options.type}`,\n        ProjectErrorCode.VALIDATION_ERROR,\n      );\n  }\n}\n","/**\n * GitHub Projects V2 implementation\n */\n\nimport { GraphQLClient, type IGraphQLClient } from '@happyvertical/graphql';\nimport { ProjectError, ProjectErrorCode } from '../errors.js';\nimport type {\n  Field,\n  IProject,\n  ItemFilters,\n  Project,\n  ProjectConfig,\n  ProjectItem,\n  Status,\n} from '../types.js';\n\n/**\n * GitHub Projects V2 implementation\n */\nexport class GitHubProject implements IProject {\n  private graphql: IGraphQLClient;\n  private projectId: string;\n  private owner?: string;\n  private repo?: string;\n  private statusFieldId?: string;\n  private statusOptions?: Record<string, string>;\n\n  constructor(config: ProjectConfig) {\n    if (config.type !== 'github') {\n      throw new Error('Invalid config type for GitHubProject');\n    }\n\n    this.graphql = new GraphQLClient({\n      endpoint: 'https://api.github.com/graphql',\n      token: config.token,\n    });\n    this.projectId = config.projectId;\n    this.owner = config.owner;\n    this.repo = config.repo;\n    this.statusFieldId = config.statusFieldId;\n    this.statusOptions = config.statusOptions;\n  }\n\n  // Project Info\n  async getProject(): Promise<Project> {\n    const query = `\n      query($projectId: ID!) {\n        node(id: $projectId) {\n          ... on ProjectV2 {\n            id\n            title\n            shortDescription\n            url\n            owner {\n              ... on Organization {\n                login\n              }\n              ... on User {\n                login\n              }\n            }\n            fields(first: 20) {\n              nodes {\n                ... on ProjectV2Field {\n                  id\n                  name\n                  dataType\n                }\n                ... on ProjectV2SingleSelectField {\n                  id\n                  name\n                  dataType\n                  options {\n                    id\n                    name\n                    description\n                    color\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    `;\n\n    const data = (await this.graphql.query(query, {\n      projectId: this.projectId,\n    })) as {\n      node: {\n        id: string;\n        title: string;\n        shortDescription: string;\n        url: string;\n        owner: { login: string };\n        fields: {\n          nodes: Array<{\n            id: string;\n            name: string;\n            dataType: string;\n            options?: Array<{\n              id: string;\n              name: string;\n              description?: string;\n              color?: string;\n            }>;\n          }>;\n        };\n      };\n    };\n\n    const statusField = data.node.fields.nodes.find(\n      (f) => f.name === 'Status' && f.options,\n    );\n\n    return {\n      id: data.node.id,\n      title: data.node.title,\n      description: data.node.shortDescription,\n      owner: data.node.owner.login,\n      url: data.node.url,\n      statuses: statusField?.options\n        ? statusField.options.map((opt, index) => ({\n            id: opt.id,\n            name: opt.name,\n            description: opt.description,\n            color: opt.color,\n            order: index,\n          }))\n        : [],\n      fields: data.node.fields.nodes.map((f) => ({\n        id: f.id,\n        name: f.name,\n        type: this.mapFieldType(f.dataType),\n        options: f.options?.map((opt) => ({\n          id: opt.id,\n          name: opt.name,\n          description: opt.description,\n          color: opt.color,\n        })),\n      })),\n    };\n  }\n\n  // Items\n  async addItem(contentId: string): Promise<ProjectItem> {\n    const mutation = `\n      mutation($projectId: ID!, $contentId: ID!) {\n        addProjectV2ItemById(input: {\n          projectId: $projectId\n          contentId: $contentId\n        }) {\n          item {\n            id\n            content {\n              ... on Issue {\n                id\n              }\n              ... on PullRequest {\n                id\n              }\n            }\n          }\n        }\n      }\n    `;\n\n    const data = (await this.graphql.mutate(mutation, {\n      projectId: this.projectId,\n      contentId,\n    })) as {\n      addProjectV2ItemById: {\n        item: {\n          id: string;\n          content: {\n            id: string;\n          };\n        };\n      };\n    };\n\n    return {\n      id: data.addProjectV2ItemById.item.id,\n      contentId: data.addProjectV2ItemById.item.content.id,\n      fields: {},\n      type: 'Issue',\n    };\n  }\n\n  async removeItem(itemId: string): Promise<void> {\n    const mutation = `\n      mutation($projectId: ID!, $itemId: ID!) {\n        deleteProjectV2Item(input: {\n          projectId: $projectId\n          itemId: $itemId\n        }) {\n          deletedItemId\n        }\n      }\n    `;\n\n    await this.graphql.mutate(mutation, {\n      projectId: this.projectId,\n      itemId,\n    });\n  }\n\n  async getItem(itemId: string): Promise<ProjectItem | null> {\n    const query = `\n      query($itemId: ID!) {\n        node(id: $itemId) {\n          ... on ProjectV2Item {\n            id\n            content {\n              ... on Issue {\n                id\n              }\n              ... on PullRequest {\n                id\n              }\n            }\n          }\n        }\n      }\n    `;\n\n    const data = (await this.graphql.query(query, { itemId })) as {\n      node: {\n        id: string;\n        content: {\n          id: string;\n        };\n      } | null;\n    };\n\n    if (!data.node) {\n      return null;\n    }\n\n    return {\n      id: data.node.id,\n      contentId: data.node.content.id,\n      fields: {},\n      type: 'Issue',\n    };\n  }\n\n  async listItems(filters?: ItemFilters): Promise<ProjectItem[]> {\n    const query = `\n      query($projectId: ID!, $first: Int!, $after: String) {\n        node(id: $projectId) {\n          ... on ProjectV2 {\n            items(first: $first, after: $after) {\n              nodes {\n                id\n                content {\n                  ... on Issue {\n                    id\n                  }\n                  ... on PullRequest {\n                    id\n                  }\n                }\n              }\n              pageInfo {\n                hasNextPage\n                endCursor\n              }\n            }\n          }\n        }\n      }\n    `;\n\n    const data = (await this.graphql.query(query, {\n      projectId: this.projectId,\n      first: filters?.limit || 100,\n      after: filters?.cursor,\n    })) as {\n      node: {\n        items: {\n          nodes: Array<{\n            id: string;\n            content: {\n              id: string;\n            };\n          }>;\n        };\n      };\n    };\n\n    return data.node.items.nodes.map((item) => ({\n      id: item.id,\n      contentId: item.content.id,\n      fields: {},\n      type: 'Issue' as const,\n    }));\n  }\n\n  // Status Management\n  async updateItemStatus(itemId: string, status: string): Promise<void> {\n    if (!this.statusFieldId || !this.statusOptions) {\n      throw new ProjectError(\n        'Status field configuration is required. Provide statusFieldId and statusOptions in config.',\n        ProjectErrorCode.INVALID_STATUS,\n      );\n    }\n\n    const statusOptionId = this.statusOptions[status];\n    if (!statusOptionId) {\n      throw new ProjectError(\n        `Status \"${status}\" not found in project configuration. Available: ${Object.keys(this.statusOptions).join(', ')}`,\n        ProjectErrorCode.INVALID_STATUS,\n      );\n    }\n\n    await this.updateItemField(itemId, this.statusFieldId, statusOptionId);\n  }\n\n  async listStatuses(): Promise<Status[]> {\n    const project = await this.getProject();\n    return project.statuses;\n  }\n\n  // Field Management\n  async updateItemField(\n    itemId: string,\n    fieldId: string,\n    value: unknown,\n  ): Promise<void> {\n    const mutation = `\n      mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $value: ProjectV2FieldValue!) {\n        updateProjectV2ItemFieldValue(input: {\n          projectId: $projectId\n          itemId: $itemId\n          fieldId: $fieldId\n          value: $value\n        }) {\n          projectV2Item {\n            id\n          }\n        }\n      }\n    `;\n\n    await this.graphql.mutate(mutation, {\n      projectId: this.projectId,\n      itemId,\n      fieldId,\n      value: { singleSelectOptionId: value },\n    });\n  }\n\n  async listFields(): Promise<Field[]> {\n    const project = await this.getProject();\n    return project.fields;\n  }\n\n  /**\n   * Map GitHub field type to our standard types\n   */\n  private mapFieldType(\n    dataType: string,\n  ): 'text' | 'number' | 'date' | 'single_select' | 'iteration' {\n    switch (dataType.toLowerCase()) {\n      case 'text':\n        return 'text';\n      case 'number':\n        return 'number';\n      case 'date':\n        return 'date';\n      case 'single_select':\n        return 'single_select';\n      case 'iteration':\n        return 'iteration';\n      default:\n        return 'text';\n    }\n  }\n}\n","/**\n * Core types for project management operations\n */\n\nexport interface Project {\n  id: string;\n  title: string;\n  description?: string;\n  owner: string; // Organization or user\n  url: string;\n  statuses: Status[];\n  fields: Field[];\n}\n\nexport interface ProjectItem {\n  id: string; // Project item ID\n  contentId: string; // Issue/PR node ID\n  status?: string;\n  fields: Record<string, unknown>;\n  type: 'Issue' | 'PullRequest' | 'DraftIssue';\n}\n\nexport interface Status {\n  id: string;\n  name: string;\n  description?: string;\n  color?: string;\n  order: number;\n}\n\nexport interface Field {\n  id: string;\n  name: string;\n  type: 'text' | 'number' | 'date' | 'single_select' | 'iteration';\n  options?: FieldOption[];\n}\n\nexport interface FieldOption {\n  id: string;\n  name: string;\n  description?: string;\n  color?: string;\n}\n\nexport interface ItemFilters {\n  status?: string;\n  assignees?: string[];\n  labels?: string[];\n  limit?: number;\n  cursor?: string; // For pagination\n}\n\n/**\n * Project configuration\n */\nexport interface ProjectConfig {\n  type: 'github' | 'jira' | 'zenhub' | 'linear';\n  projectId: string;\n  token: string;\n\n  // GitHub Projects V2\n  owner?: string; // Organization or user\n  repo?: string; // Repository name (for repo-level projects)\n  statusFieldId?: string;\n  statusOptions?: Record<string, string>; // Map status name to option ID\n\n  // Jira\n  boardId?: string;\n\n  // Linear\n  teamId?: string;\n}\n\n/**\n * Kanban status names for 6-lane structure\n */\nexport const KANBAN_STATUSES = [\n  'New',\n  'Backlog',\n  'Planning',\n  'Ready',\n  'In Progress',\n  'Review',\n  'Done',\n] as const;\n\nexport type KanbanStatus = (typeof KANBAN_STATUSES)[number];\n\n/**\n * Project interface - all project implementations must implement this\n */\nexport interface IProject {\n  // Project Info\n  getProject(): Promise<Project>;\n\n  // Items (Issues/Cards)\n  addItem(contentId: string): Promise<ProjectItem>;\n  removeItem(itemId: string): Promise<void>;\n  getItem(itemId: string): Promise<ProjectItem | null>;\n  listItems(filters?: ItemFilters): Promise<ProjectItem[]>;\n\n  // Status/Column Management\n  updateItemStatus(itemId: string, status: string): Promise<void>;\n  listStatuses(): Promise<Status[]>;\n\n  // Field Management\n  updateItemField(\n    itemId: string,\n    fieldId: string,\n    value: unknown,\n  ): Promise<void>;\n  listFields(): Promise<Field[]>;\n}\n"],"names":["ProjectErrorCode","GitHubProject","index"],"mappings":"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"}

package/metadata.json

@@ -0,0 +1,31 @@
+{
+  "name": "@happyvertical/projects",
+  "path": "packages/projects",
+  "position": {
+    "index": 21,
+    "count": 30
+  },
+  "description": "Standardized project management interface for GitHub Projects, Jira, ZenHub, and Linear",
+  "provides": [
+    "Standardized project management interface for GitHub Projects, Jira, ZenHub, and Linear"
+  ],
+  "implements": [],
+  "requires": {
+    "workspace": [
+      "@happyvertical/graphql",
+      "@happyvertical/repos"
+    ],
+    "externalHappyVertical": [],
+    "external": []
+  },
+  "dependents": [
+    "@happyvertical/github-actions"
+  ],
+  "stability": {
+    "level": "stable",
+    "reason": "Primary package surface is described as implemented and production-oriented."
+  },
+  "keywords": [
+    "projects"
+  ]
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@happyvertical/projects",
+  "version": "0.74.8",
+  "description": "Standardized project management interface for GitHub Projects, Jira, ZenHub, and Linear",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "have-projects-context": "./dist/cli/claude-context.js"
+  },
+  "dependencies": {
+    "@happyvertical/graphql": "0.74.8",
+    "@happyvertical/repos": "0.74.8"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.10",
+    "typescript": "^5.9.3",
+    "vite": "7.3.2",
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "4.1.5"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "AGENT.md",
+    "metadata.json"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/sdk.git",
+    "directory": "packages/projects"
+  },
+  "bugs": {
+    "url": "https://github.com/happyvertical/sdk/issues"
+  },
+  "homepage": "https://github.com/happyvertical/sdk/tree/main/packages/projects#readme",
+  "license": "MIT",
+  "scripts": {
+    "test": "npx vitest run --passWithNoTests",
+    "test:watch": "npx vitest",
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "clean": "rm -rf dist",
+    "dev": "npm run build:watch & npm run test:watch"
+  }
+}