diff --git a/docs/site/docs/reference/api.md b/docs/site/docs/reference/api.md index 15ff60b..36c4eac 100644 --- a/docs/site/docs/reference/api.md +++ b/docs/site/docs/reference/api.md @@ -6,7 +6,7 @@ sidebar_position: 2 # API -The issue-tracker is the user-facing Tasq API. It owns project, issue, comment, attachment, workflow, and summary data. +The issue-tracker is the user-facing Tasq API. It owns project, issue, artifact, comment, change-request, attachment, workflow, and summary data. ## Response Envelope @@ -48,6 +48,11 @@ Error responses use: | `GET` | `/api/v1/issues/{issueId}/comments` | List comments. | | `POST` | `/api/v1/issues/{issueId}/comments` | Add a comment. | | `PATCH` | `/api/v1/comments/{id}` | Update a comment. | +| `GET` | `/api/v1/issues/{issueId}/change-requests` | List change requests for an issue. | +| `POST` | `/api/v1/issues/{issueId}/change-requests` | Create an open change request. | +| `GET` | `/api/v1/change-requests/{id}` | Read a change request. | +| `PATCH` | `/api/v1/change-requests/{id}` | Edit the body while `open`, or perform an allowed status transition. | +| `POST` | `/api/v1/change-requests/{id}/cancel` | Cancel an open or in-progress change request. | | `GET` | `/api/v1/attachments` | List attachments. | | `POST` | `/api/v1/attachments` | Upload an attachment. | | `GET` | `/api/v1/attachments/{id}/content` | Download attachment bytes. | @@ -61,8 +66,16 @@ Issue listing supports filters for `states`, `project_id`, `project_ids`, Comment listing supports `cursor` and `limit`. Attachment listing supports `entity_type` and `entity_id`. +Change-request listing supports an optional `status` filter and `limit` from `1` to `100`, defaulting to `50`. + Issue responses always include an `artifacts` array, sorted by `type`, including `[]` when no artifacts exist. The initial `pull_request` artifact accepts only `data_value` on `PUT`; the server returns `type`, `data_type`, and `data_value`. `DELETE` returns an empty `204`. Invalid types or URLs return `400`; a missing issue or artifact returns `404`. +Change requests capture additional work for a later agent run. Creation sets the status to `open`. Allowed transitions are `open` to `in_progress` or `canceled`, and `in_progress` to `resolved` or `canceled`. Resolved and canceled requests are immutable. Cancellation is a state transition; there is no physical delete endpoint. + +## Contract Sources + +The [issue-tracker OpenAPI document](https://github.com/version-1/tasq/blob/main/docs/openapi/issue-tracker.yml) and [orchestrator OpenAPI document](https://github.com/version-1/tasq/blob/main/docs/openapi/orchestrator.yml) define request parameters, bodies, responses, and error status codes. This page is the concise endpoint and behavior reference. + ## Attachments Attachment uploads use multipart form data with `entity_type`, `entity_id`, and `file`. Supported image types are PNG, JPEG, GIF, and WebP up to 5 MiB. diff --git a/docs/site/docs/reference/cli-reference.md b/docs/site/docs/reference/cli-reference.md index 064348c..6a94b1c 100644 --- a/docs/site/docs/reference/cli-reference.md +++ b/docs/site/docs/reference/cli-reference.md @@ -6,7 +6,7 @@ sidebar_position: 1 # CLI Reference -`tq` is the command-line interface for issue management, project setup, workflow configuration, local services, logs, migrations, and the Web UI. +`tq` is the command-line interface for issue management, project setup, workflow configuration, raw API access, local services, logs, migrations, and the Web and terminal UIs. ## Global Form @@ -31,7 +31,7 @@ API URL resolution order is `--api-url`, `TQ_API_URL`, `$TQ_HOME/system/state.js | `tq issue update [flags]` | Update issue fields. | | `tq issue watch [--interval ] [--seen-ttl ] [--verbose]` | Poll ready issues and emit JSON event envelopes. | | `tq issue close ` | Move an issue to `done`. | -| `tq issue cancel ` | Move an issue to `failed`. | +| `tq issue cancel ` | Move an issue to `cancelled`. | | `tq issue ready ` | Move an issue to `ready`. | | `tq issue draft ` | Move an issue to `backlog`. | | `tq issue rename ` | Update the title. | @@ -88,12 +88,37 @@ Allowed comment types are `progress`, `blocker`, `handoff`, and `general`. | `tq migrate down` | Roll back migrations. | | `tq migrate status` | Show migration status. | | `tq web` | Open the running Web UI. | +| `tq tui` | Open the experimental read-only terminal UI. Aliases: `tq console`, `tq c`. | +| `tq config` | Show build, home-directory, and resolved configuration information. | | `tq version` | Print version information. | | `tq update [-y] [--tag <tag>]` | Install a release, migrate databases, and restart services. | Log services are `tracker` or `issue-tracker`, `orchestrator`, and `web`. +`tq tui [--orchestrator-url URL]` requires a terminal and supports only text output. It reads issues, comments, artifacts, and run state without sending mutation requests. Use `--orchestrator-url` to override orchestrator discovery from `state.json`. + +`tq config` prints the version, build profile, `TQ_HOME` override, resolved home directory, configuration file path, and resolved values. It does not print the raw YAML. Use global `--output json` for scripts. + `tq update` prints the current and target versions, confirms that local services will stop and restart, installs the latest formal release by default, verifies the newly installed `tq version`, runs migrations, and starts services. `-y` skips the confirmation prompt. `--tag` installs a specific release or prerelease tag. +`tq update` is unavailable when the binary has a non-empty build profile such as `dev`, because generic release artifacts do not retain that profile. + For step-by-step examples and service interruption guidance, see [Update Tasq](pathname:///guides/update-tasq). + +## Raw API Command + +Use `tq api` for an issue-tracker operation that has no typed command: + +```sh +tq api GET /api/v1/issues --query states=ready +tq api POST /api/v1/issues --header 'X-Request-ID: local-123' --data @request.json +``` + +```text +tq api <method> <path> [--query key=value] [--header 'Name: value'] [--data value|@file|-] +``` + +The path must be an allowlisted, unencoded absolute `/api/v1/...` path. Complete URLs, fragments, dot segments, empty segments, and trailing slashes are rejected. `--query` and `--header` are repeatable. `--data` accepts a literal value, `@file`, or `-` for standard input and is available only for `POST`, `PUT`, and `PATCH`. + +The command does not prompt before writes or deletes, does not follow redirects, and times out after 10 seconds. Response bytes are written unchanged, so global `--output` does not transform them. Exit status is `0` for HTTP `2xx`, `1` for HTTP or transport failures, and `2` for invalid usage, input, or a request outside the allowlist. diff --git a/docs/site/docs/reference/configuration.md b/docs/site/docs/reference/configuration.md index 54a8691..323a5fd 100644 --- a/docs/site/docs/reference/configuration.md +++ b/docs/site/docs/reference/configuration.md @@ -14,6 +14,8 @@ By default, `TQ_HOME` resolves to `~/.tasq`. For repository-local development, s export TQ_HOME="$PWD/.tasq" ``` +Development binaries may embed a lowercase build profile such as `dev`, which changes the default home to `~/.tasq-dev`. An explicit `TQ_HOME` always wins. All sibling executables must use the same profile so `tq`, issue-tracker, orchestrator, and Web UI discover the same state. + ## Directory Layout ```text @@ -34,6 +36,8 @@ $TQ_HOME/ `config/` is user-editable. `system/` is managed by Tasq processes. +Run `tq config` to inspect the version, build profile, `TQ_HOME` override, resolved home, configuration path, and resolved values. Use `tq --output json config` for machine-readable output. + ## config.yaml ```yaml diff --git a/docs/site/docs/reference/schema.md b/docs/site/docs/reference/schema.md index 4793120..4048c04 100644 --- a/docs/site/docs/reference/schema.md +++ b/docs/site/docs/reference/schema.md @@ -15,6 +15,7 @@ Tasq validates entity data at the store layer on create and update operations. T | Issue | `projectId`, `title` | title 1-500 chars, description max 10,000 chars, assignee max 200 chars, immutable project ownership | | Artifact | `type`, `dataType`, `dataValue` | one per issue and type; initial type `pull_request` has data type `url`; URL is trimmed, absolute HTTP(S), host-required, userinfo-free, max 4,096 UTF-8 bytes | | Comment | `issueId`, `author`, `body` | body 1-10,000 chars, type defaults to `general` | +| ChangeRequest | `issueId`, `author`, `body` | body 1-10,000 chars and editable only while `open`; status defaults to `open`; terminal requests are immutable | | Attachment | `entityType`, `entityId`, `file` | image PNG/JPEG/GIF/WebP, max 5 MiB | | Project | `key`, `name`, `location` | key format, name 1-200 chars, description max 10,000 chars, absolute location | | ProjectWorkflow | `projectId`, `frontmatter`, `body`, `checksum` | one workflow override per project, checksum is SHA256 hex | @@ -36,6 +37,7 @@ Tasq validates entity data at the store layer on create and update operations. T | Queue status | `backlog`, `pending`, `queued`, `processing`, `completed`, `inactive` | | Issue priority | `low`, `normal`, `high`, `urgent` | | Comment type | `progress`, `blocker`, `handoff`, `general` | +| Change-request status | `open`, `in_progress`, `resolved`, `canceled` | | Attachment entity type | `issue`, `comment` | | Artifact type | `pull_request` | | Artifact data type | `url` | @@ -53,3 +55,7 @@ flowchart TD ``` Absolute path fields must start with `/`. Clients such as `tq project add` check local directory existence when they can access the target filesystem. + +## State Transitions + +Change requests allow `open` to `in_progress` or `canceled`, and `in_progress` to `resolved` or `canceled`. Resolving can record the orchestrator run and a result comment on the same issue. `resolved` and `canceled` are terminal states. diff --git a/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/api.md b/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/api.md index 3b581b1..d6f6080 100644 --- a/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/api.md +++ b/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/api.md @@ -4,25 +4,25 @@ title: API sidebar_position: 2 --- -# API +# API リファレンス -issue-tracker は user-facing Tasq API です。project、issue、comment、attachment、workflow、summary data を所有します。 +Issue Tracker は利用者向けの Tasq API です。プロジェクト、課題、Artifact、コメント、change request、添付ファイル、ワークフロー、サマリーのデータを所有します。 -## Response Envelope +## レスポンス形式 -success responses は次を使います。 +成功時のレスポンスは次の形式です。 ```json { "data": {}, "meta": {} } ``` -error responses は次を使います。 +エラー時のレスポンスは次の形式です。 ```json { "error": { "code": "invalid_request", "message": "..." }, "meta": {} } ``` -## Issue-Tracker Endpoints +## Issue Tracker エンドポイント | Method | Path | Purpose | | --- | --- | --- | @@ -48,6 +48,11 @@ error responses は次を使います。 | `GET` | `/api/v1/issues/{issueId}/comments` | comments を list します。 | | `POST` | `/api/v1/issues/{issueId}/comments` | comment を追加します。 | | `PATCH` | `/api/v1/comments/{id}` | comment を更新します。 | +| `GET` | `/api/v1/issues/{issueId}/change-requests` | 課題の change request を一覧表示します。 | +| `POST` | `/api/v1/issues/{issueId}/change-requests` | `open` 状態の change request を作成します。 | +| `GET` | `/api/v1/change-requests/{id}` | change request を取得します。 | +| `PATCH` | `/api/v1/change-requests/{id}` | `open` の間に本文を編集するか、許可された状態遷移を行います。 | +| `POST` | `/api/v1/change-requests/{id}/cancel` | `open` または `in_progress` の change request を取り消します。 | | `GET` | `/api/v1/attachments` | attachments を list します。 | | `POST` | `/api/v1/attachments` | attachment を upload します。 | | `GET` | `/api/v1/attachments/{id}/content` | attachment bytes を download します。 | @@ -61,9 +66,17 @@ issue listing では `states`、`project_id`、`project_ids`、`priorities`、 comment listing は `cursor` と `limit` を受け付けます。attachment listing は `entity_type` と `entity_id` を受け付けます。 +change request の一覧取得では、任意の `status` フィルターと `1`〜`100` の `limit` を指定できます。`limit` の既定値は `50` です。 + 課題レスポンスには、Artifact がない場合も `[]` となる `artifacts` 配列が常に含まれ、`type` 昇順で返ります。初期の `pull_request` Artifact では、`PUT` に `data_value` だけを指定します。サーバーは `type`、`data_type`、`data_value` を返します。`DELETE` は本文のない `204` を返します。不正な type または URL は `400`、課題または Artifact が存在しない場合は `404` です。 -## Attachments +change request は、後続のエージェント実行で対応する追加作業を記録します。作成時の状態は `open` です。許可される状態遷移は `open` から `in_progress` または `canceled`、`in_progress` から `resolved` または `canceled` です。`resolved` と `canceled` は変更できません。取り消しは状態遷移として扱われ、物理削除のエンドポイントはありません。 + +## コントラクトの参照先 + +[Issue Tracker の OpenAPI 文書](https://github.com/version-1/tasq/blob/main/docs/openapi/issue-tracker.yml)と [orchestrator の OpenAPI 文書](https://github.com/version-1/tasq/blob/main/docs/openapi/orchestrator.yml)が、リクエストパラメーター、本文、レスポンス、エラーステータスを定義します。このページはエンドポイントと動作の要約です。 + +## 添付ファイル Attachment uploads は `entity_type`、`entity_id`、`file` を含む multipart form data を使います。supported image types は PNG、JPEG、GIF、WebP で、上限は 5 MiB です。 diff --git a/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/cli-reference.md b/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/cli-reference.md index d748feb..566efa4 100644 --- a/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/cli-reference.md +++ b/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/cli-reference.md @@ -4,9 +4,9 @@ title: CLI Reference sidebar_position: 1 --- -# CLI Reference +# CLI リファレンス -`tq` は issue management、project setup、workflow configuration、local services、logs、migrations、Web UI のための command-line interface です。 +`tq` は、課題管理、プロジェクト設定、ワークフロー設定、API への直接アクセス、ローカルサービス、ログ、マイグレーション、Web UI、ターミナル UI を操作するコマンドラインインターフェースです。 ## 全体の形式 @@ -14,37 +14,35 @@ sidebar_position: 1 tq [--api-url URL] [--output text|json] <resource> <action> [flags] ``` -| Flag | Description | +| フラグ | 説明 | | --- | --- | -| `--api-url URL` | Issue-tracker API URL。environment と state discovery を override します。 | -| `--output text\|json` | Output format。default は `text` です。 | +| `--api-url URL` | Issue Tracker API の URL。環境変数と状態ファイルによる検出を上書きします。 | +| `--output text\|json` | 出力形式。既定値は `text` です。 | -API URL resolution order は `--api-url`、`TQ_API_URL`、`$TQ_HOME/system/state.json`、最後に `http://localhost:37651` です。 +API URL は `--api-url`、`TQ_API_URL`、`$TQ_HOME/system/state.json`、`http://localhost:37651` の順で解決します。 -## Issue Commands +## 課題コマンド -| Command | Purpose | +| コマンド | 用途 | | --- | --- | -| `tq issue list [--project <key>]` | issues を list します。任意で 1 project に scope できます。 | -| `tq issue get <id>` | 1 つの issue を表示します。 | -| `tq issue create --project <key> --title <title>` | issue を作成します。 | -| `tq issue update <id> [flags]` | issue fields を更新します。 | -| `tq issue watch [--interval <duration>] [--seen-ttl <duration>] [--verbose]` | ready な issue を polling し、JSON event envelopes を出力します。 | -| `tq issue close <id>` | issue を `done` に移動します。 | -| `tq issue cancel <id>` | issue を `failed` に移動します。 | -| `tq issue ready <id>` | issue を `ready` に移動します。 | -| `tq issue draft <id>` | issue を `backlog` に移動します。 | -| `tq issue rename <id> <title>` | title を更新します。 | -| `tq issue edit <id> <description>` | description を更新します。 | +| `tq issue list [--project <key>]` | 課題を一覧表示します。プロジェクトを指定して絞り込めます。 | +| `tq issue get <id>` | 1 件の課題を表示します。 | +| `tq issue create --project <key> --title <title>` | 課題を作成します。 | +| `tq issue update <id> [flags]` | 課題のフィールドを更新します。 | +| `tq issue watch [--interval <duration>] [--seen-ttl <duration>] [--verbose]` | 実行可能な課題を定期取得し、JSON イベントを出力します。 | +| `tq issue close <id>` | 課題を `done` に移動します。 | +| `tq issue cancel <id>` | 課題を `cancelled` に移動します。 | +| `tq issue ready <id>` | 課題を `ready` に移動します。 | +| `tq issue draft <id>` | 課題を `backlog` に移動します。 | +| `tq issue rename <id> <title>` | タイトルを更新します。 | +| `tq issue edit <id> <description>` | 説明を更新します。 | create と update は、該当する場合に `--title`、`--description`、`--status`、 `--priority`、`--assignee`、`--attach` を受け付けます。update では、依存関係を 置き換える `--dependency <comma-separated-ids>` と、依存関係を削除する `--clear-dependencies` も指定できます。 -`tq issue watch` はエージェントの loop で使うことを想定しています。ready queue を -読み、設定された seen TTL の間は同じ issue の出力を重複排除し、`issue-ready` event -を出力します。一時的な API error が起きても polling を継続します。 +`tq issue watch` はエージェントのループ処理向けです。実行待ちキューを読み、設定された TTL の間は同じ課題を重複して出力せず、`issue-ready` イベントを出力します。一時的な API エラーが起きても取得を継続します。 ## Artifact コマンド @@ -55,30 +53,30 @@ create と update は、該当する場合に `--title`、`--description`、`--s どちらのコマンドも正の課題 ID と `--type` を必要とし、グローバルな text / JSON 出力モードに対応します。 -## Comment Commands +## コメントコマンド -| Command | Purpose | +| コマンド | 用途 | | --- | --- | -| `tq comment add <issue-id> --body <body>` | comment を追加します。 | -| `tq comment list <issue-id>` | issue の comments を list します。 | +| `tq comment add <issue-id> --body <body>` | コメントを追加します。 | +| `tq comment list <issue-id>` | 課題のコメントを一覧表示します。 | -許可される comment types は `progress`、`blocker`、`handoff`、`general` です。 +コメント種別には `progress`、`blocker`、`handoff`、`general` を指定できます。 -## Project and Workflow Commands +## プロジェクトとワークフローのコマンド -| Command | Purpose | +| コマンド | 用途 | | --- | --- | -| `tq project add [path] [--key <key>]` | repository を登録します。 | -| `tq project remove [-y] <key>` | key 入力確認後に project を削除します。`-y` で prompt を skip できます。 | -| `tq project check [key]` | project setup を validate します。 | -| `tq project list` | registered projects を list します。 | -| `tq workflow add --project <key> (--file <path> \| --body <text>)` | workflow override を保存します。 | -| `tq workflow remove --project <key>` | stored override を削除します。 | -| `tq workflow show --project <key> [--json]` | resolved workflow を表示します。 | +| `tq project add [path] [--key <key>]` | リポジトリを登録します。 | +| `tq project remove [-y] <key>` | キー入力による確認後にプロジェクトを削除します。`-y` で確認を省略できます。 | +| `tq project check [key]` | プロジェクト設定を検証します。 | +| `tq project list` | 登録済みプロジェクトを一覧表示します。 | +| `tq workflow add --project <key> (--file <path> \| --body <text>)` | ワークフローの上書きを保存します。 | +| `tq workflow remove --project <key>` | 保存済みの上書きを削除します。 | +| `tq workflow show --project <key> [--json]` | 解決済みワークフローを表示します。 | -## Runtime Commands +## 実行環境のコマンド -| Command | Purpose | +| コマンド | 用途 | | --- | --- | | `tq service start` | issue-tracker、orchestrator、Web UI を起動します。 | | `tq service stop` | local services を停止します。 | @@ -88,11 +86,36 @@ create と update は、該当する場合に `--title`、`--description`、`--s | `tq migrate down` | migrations を rollback します。 | | `tq migrate status` | migration status を表示します。 | | `tq web` | 実行中の Web UI を開きます。 | -| `tq version` | version information を出力します。 | -| `tq update [-y] [--tag <tag>]` | release を install し、databases を migrate して services を再起動します。 | +| `tq tui` | 実験的な読み取り専用ターミナル UI を開きます。別名は `tq console` と `tq c` です。 | +| `tq config` | ビルド、ホームディレクトリ、解決済み設定を表示します。 | +| `tq version` | バージョン情報を出力します。 | +| `tq update [-y] [--tag <tag>]` | リリースをインストールし、データベースを移行してサービスを再起動します。 | -log service には `tracker` または `issue-tracker`、`orchestrator`、`web` を指定できます。 +ログ対象には `tracker` または `issue-tracker`、`orchestrator`、`web` を指定できます。 + +`tq tui [--orchestrator-url URL]` はターミナルを必要とし、テキスト出力だけに対応します。課題、コメント、Artifact、実行状態を読み取りますが、データを変更するリクエストは送信しません。`--orchestrator-url` を指定すると、`state.json` による orchestrator の検出を上書きできます。 + +`tq config` は、バージョン、ビルドプロファイル、`TQ_HOME` の上書き、解決済みホームディレクトリ、設定ファイルのパス、解決済みの値を表示します。YAML の生データは表示しません。スクリプトではグローバルオプションの `--output json` を使用します。 `tq update` は現在のバージョンと更新先のバージョンを表示し、ローカルサービスの停止と再起動が入ることを確認してから、既定では最新の正式リリースをインストールします。その後、新しくインストールされた `tq version` を確認し、マイグレーションを実行してサービスを起動します。`-y` は確認プロンプトを省略します。`--tag` は特定のリリースまたはプレリリースのタグをインストールします。 +`dev` など空でないビルドプロファイルを持つバイナリでは、汎用のリリース成果物がそのプロファイルを保持しないため、`tq update` を使用できません。 + 具体的な手順とサービス停止時の注意事項は、[Tasq を更新する](pathname:///guides/update-tasq)を参照してください。 + +## API 直接実行コマンド + +型付きコマンドがない Issue Tracker 操作には `tq api` を使用します。 + +```sh +tq api GET /api/v1/issues --query states=ready +tq api POST /api/v1/issues --header 'X-Request-ID: local-123' --data @request.json +``` + +```text +tq api <method> <path> [--query key=value] [--header 'Name: value'] [--data value|@file|-] +``` + +パスには許可リストに含まれる、エンコードされていない絶対 `/api/v1/...` パスを指定します。完全な URL、フラグメント、ドットセグメント、空セグメント、末尾のスラッシュは拒否されます。`--query` と `--header` は繰り返し指定できます。`--data` にはリテラル値、`@file`、または標準入力を表す `-` を指定でき、`POST`、`PUT`、`PATCH` でだけ使用できます。 + +書き込みや削除の前に確認プロンプトは表示されず、リダイレクトにも追従しません。タイムアウトは 10 秒です。レスポンスのバイト列をそのまま出力するため、グローバルな `--output` は変換に使われません。終了コードは HTTP `2xx` で `0`、HTTP または通信エラーで `1`、使い方、入力、許可リストの検証エラーで `2` です。 diff --git a/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/configuration.md b/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/configuration.md index d69593c..02dea0a 100644 --- a/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/configuration.md +++ b/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/configuration.md @@ -4,16 +4,18 @@ title: Configuration sidebar_position: 3 --- -# Configuration +# 設定リファレンス -Tasq は machine-level configuration、runtime state、service logs、SQLite data の local home directory として `TQ_HOME` を使います。 +Tasq は、マシン単位の設定、実行状態、サービスログ、SQLite データを保存するローカルホームディレクトリとして `TQ_HOME` を使います。 -default では `TQ_HOME` は `~/.tasq` に解決されます。repository-local development では workspace directory に設定してください。 +既定では `TQ_HOME` は `~/.tasq` です。リポジトリ内で開発する場合は、ワークスペース内のディレクトリを指定してください。 ```sh export TQ_HOME="$PWD/.tasq" ``` +開発用バイナリには、`dev` のような小文字のビルドプロファイルを埋め込めます。この場合、既定のホームは `~/.tasq-dev` になります。`TQ_HOME` を明示した場合は常にそちらが優先されます。`tq`、Issue Tracker、orchestrator、Web UI が同じ状態を検出できるよう、すべてのバイナリで同じプロファイルを使用してください。 + ## Directory Layout ```text @@ -32,7 +34,9 @@ $TQ_HOME/ └── attachments/ ``` -`config/` は user-editable です。`system/` は Tasq processes が管理します。 +`config/` は利用者が編集します。`system/` は Tasq のプロセスが管理します。 + +`tq config` を実行すると、バージョン、ビルドプロファイル、`TQ_HOME` の上書き、解決済みホーム、設定ファイルのパス、解決済みの値を確認できます。機械可読な出力には `tq --output json config` を使用します。 ## config.yaml diff --git a/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/schema.md b/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/schema.md index 66a6ea6..48d949a 100644 --- a/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/schema.md +++ b/docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/schema.md @@ -4,9 +4,9 @@ title: Schema sidebar_position: 4 --- -# Schema +# スキーマリファレンス -Tasq は create と update operations において store layer で entity data を validate します。この reference は clients が守るべき public field constraints を要約します。 +Tasq は作成・更新時に、ストア層でエンティティのデータを検証します。このページでは、クライアントが守るべき公開フィールドの制約を要約します。 ## Issue Tracker Entities @@ -15,6 +15,7 @@ Tasq は create と update operations において store layer で entity data | Issue | `projectId`, `title` | title 1-500 chars、description max 10,000 chars、assignee max 200 chars、immutable project ownership | | Artifact | `type`, `dataType`, `dataValue` | 課題と type の組み合わせごとに 1 件。初期 type の `pull_request` は data type `url`。URL は前後の空白を除去し、絶対 HTTP(S) URL、host 必須、userinfo なし、UTF-8 で最大 4,096 bytes | | Comment | `issueId`, `author`, `body` | body 1-10,000 chars、type defaults to `general` | +| ChangeRequest | `issueId`, `author`, `body` | 本文は 1〜10,000 文字で、`open` の間だけ編集可能。状態の既定値は `open`。終端状態では変更不可 | | Attachment | `entityType`, `entityId`, `file` | image PNG/JPEG/GIF/WebP、max 5 MiB | | Project | `key`, `name`, `location` | key format、name 1-200 chars、description max 10,000 chars、absolute location | | ProjectWorkflow | `projectId`, `frontmatter`, `body`, `checksum` | one workflow override per project、checksum は SHA256 hex | @@ -36,6 +37,7 @@ Tasq は create と update operations において store layer で entity data | Queue status | `backlog`, `pending`, `queued`, `processing`, `completed`, `inactive` | | Issue priority | `low`, `normal`, `high`, `urgent` | | Comment type | `progress`, `blocker`, `handoff`, `general` | +| Change request status | `open`, `in_progress`, `resolved`, `canceled` | | Attachment entity type | `issue`, `comment` | | Artifact type | `pull_request` | | Artifact data type | `url` | @@ -52,4 +54,8 @@ flowchart TD Payload[50,000 chars] --> JSON[runner event payload JSON] ``` -absolute path fields は `/` で始まる必要があります。`tq project add` のような clients は、target filesystem に access できる場合に local directory existence を確認します。 +絶対パスのフィールドは `/` で始まる必要があります。`tq project add` などのクライアントは、対象ファイルシステムへアクセスできる場合にローカルディレクトリの存在を確認します。 + +## 状態遷移 + +change request は `open` から `in_progress` または `canceled`、`in_progress` から `resolved` または `canceled` へ遷移できます。解決時には orchestrator の実行 ID と、同じ課題に属する結果コメントを記録できます。`resolved` と `canceled` は終端状態です。