Mechago is a TypeScript-native runtime, build system, compatibility harness, and package ecosystem for Forge-style work-

# Product Prompt: Mechago M0 ## Product Name **Mechago** ## Product Definition Mechago is a TypeScript-native runtime, build system, compatibility harness, and package ecosystem for Forge-style work-management apps targeting Jira-compatible APIs. Mechago is not a Jira clone, not a Connect bridge, not a Java plugin framework, and not a Data Center compatibility layer. Mechago implements the app platform layer first. The first product adapter is: ```text @mechago/jira ``` The long-term platform architecture is: ```text OpenForge Specification ↓ Mechago Runtime ↓ Product Adapters ↓ Jira-compatible APIs ``` ## M0 Objective Create the executable product foundation for Mechago so that M1 through M5 can be executed as implementation milestones. M0 is complete when the repository, package architecture, development workflow, test harness, manifest model, local runtime shell, and first demo app are in place and runnable. M0 should not attempt to fully implement Forge, Jira, Marketplace, or an app store. M0 should create the project runway. ## Strategic Wedge Forge is the barrier and the opportunity. The core insight is that Marketplace partners do not primarily need another Jira implementation. They need a portable app runtime that preserves the shape of their investment: ```text manifest.yml resolver functions UI modules permissions storage events scheduled jobs web triggers product context typed API clients build and package workflow ``` Mechago gives partners a Forge-shaped development model without requiring Java, Connect, or Atlassian-hosted runtime dependency. ## Product Thesis A partner should eventually be able to build an app like this: ```bash npm create mechago-app cd my-app npm run dev mechago build mechago test mechago package ``` The app should be structured like this: ```text app/ manifest.yml src/ index.ts resolvers.ts ui/ IssuePanel.tsx ProjectPage.tsx ``` The runtime should load the manifest, validate declared permissions, register modules, start a local development host, render UI surfaces, execute resolver functions, persist storage calls, and communicate with a Jira-compatible API adapter. ## Non-Goals For M0 Do not implement a full Jira server. Do not implement Connect. Do not implement Java plugins. Do not implement Data Center plugin compatibility. Do not implement full Marketplace commerce. Do not copy proprietary source code. Do not decompile, bypass controls, circumvent access restrictions, or extract private implementation details. Do not use Atlassian as a required dependency for project execution. Do not use trademarks as product names. Use descriptive compatibility language only. ## Allowed Inputs Use independently authored code and public, developer-facing sources such as: ```text public documentation public API behavior public OpenAPI specifications public SDK usage patterns public app manifests public Marketplace metadata user-provided app examples independently authored test fixtures community-contributed compatibility reports ``` All Mechago implementation code must be original. ## Product Naming Use: ```text Mechago @mechago/* OpenForge-compatible Jira-compatible APIs Forge-style app runtime ``` Avoid: ```text Jira Mechago Mechago Jira as a product name Forge-compatible as a certification claim before validation Atlassian-compatible as a brand promise ``` Preferred phrasing: ```text Mechago is a TypeScript-native runtime for Forge-style apps targeting Jira-compatible APIs. ``` ## M0 Repository Structure Create a pnpm workspace monorepo. ```text mechago/ package.json pnpm-workspace.yaml tsconfig.base.json biome.json vitest.config.ts README.md LICENSE SECURITY.md CONTRIBUTING.md docs/ product/ vision.md m0-scope.md roadmap-m1-m5.md terminology.md legal-clean-room.md specs/ openforge-manifest.md openforge-runtime.md openforge-ui.md openforge-storage.md openforge-events.md openforge-jira-profile.md adr/ 0001-typescript-monorepo.md 0002-clean-room-implementation.md 0003-manifest-first-runtime.md 0004-jira-adapter-boundary.md packages/ cli/ manifest/ runtime/ ui/ jira/ storage/ events/ testkit/ create-app/ examples/ hello-issue-panel/ project-page-kv-demo/ ``` ## M0 Package Responsibilities ### `@mechago/manifest` Responsible for parsing, validating, normalizing, and typing Mechago manifests. M0 must support: ```yaml app: id: example.hello-world name: Hello World version: 0.0.1 modules: jira:issuePanel: - key: hello-issue-panel title: Hello Issue Panel resource: main resolver: function: resolver jira:projectPage: - key: hello-project-page title: Hello Project Page resource: main resolver: function: resolver resources: - key: main path: src/ui/index.tsx functions: - key: resolver handler: src/resolvers.handler permissions: scopes: - read:issue - write:issue - storage:app runtime: name: nodejs version: "20" ``` M0 deliverables: ```text Manifest TypeScript types JSON Schema YAML parser validation errors normalization step fixture manifests unit tests ``` ### `@mechago/runtime` Responsible for executing app functions and exposing runtime context. M0 must support: ```text resolver invocation local app context mock authenticated user mock installation context module registry resource registry permission registry structured runtime errors ``` M0 runtime context shape: ```ts export interface MechagoContext { app: { id: string; name: string; version: string; }; installation: { id: string; hostProduct: "jira"; baseUrl: string; }; user: { accountId: string; displayName: string; email?: string; }; module: { type: string; key: string; }; permissions: { scopes: string[]; }; } ``` ### `@mechago/ui` Responsible for providing a bounded React component layer that approximates Forge-style UI Kit patterns using independently authored components. M0 components: ```text Box Stack Inline Text Heading Button TextField TextArea Select Form DynamicTable Tabs Modal Lozenge Badge Spinner SectionMessage ``` M0 does not need pixel-perfect design parity. M0 must establish: ```text component names props rendering contract storybook or local preview route unit tests for renderability ``` ### `@mechago/jira` Responsible for Jira-compatible API access. M0 must implement only a typed client boundary and mock-backed local API. M0 client methods: ```ts getIssue(issueKey: string): Promise<Issue> searchIssues(query: IssueSearchRequest): Promise<IssueSearchResult> addComment(issueKey: string, body: string): Promise<Comment> getProject(projectKey: string): Promise<Project> ``` M0 must include: ```text TypeScript domain models mock API implementation HTTP client interface adapter boundary fixtures for issue, project, user, comment ``` ### `@mechago/storage` Responsible for app-scoped storage. M0 storage methods: ```ts get<T>(key: string): Promise<T | null> set<T>(key: string, value: T): Promise<void> delete(key: string): Promise<void> query(prefix: string): Promise<Array<{ key: string; value: unknown }>> ``` M0 backend: ```text local filesystem or SQLite app-scoped namespace installation-scoped namespace unit tests ``` ### `@mechago/events` Responsible for event contracts. M0 only needs event type