From daf1260533f57bfdbfbed5549e531a0b9b3ea36c Mon Sep 17 00:00:00 2001 From: Jiro Date: Fri, 14 Aug 2026 15:25:14 +0900 Subject: [PATCH 1/2] docs(site): refresh reference documentation Synchronize the English and Japanese CLI, API, configuration, and schema references with the current implementation. Document raw API access, terminal UI and config commands, change requests, and build-profile behavior.\n\nVerified with the Docusaurus production build for both locales and git diff --check. --- docs/site/docs/reference/api.md | 13 ++- docs/site/docs/reference/cli-reference.md | 27 ++++- docs/site/docs/reference/configuration.md | 4 + docs/site/docs/reference/schema.md | 6 + .../current/reference/api.md | 25 +++-- .../current/reference/cli-reference.md | 103 +++++++++++------- .../current/reference/configuration.md | 12 +- .../current/reference/schema.md | 12 +- 8 files changed, 144 insertions(+), 58 deletions(-) diff --git a/docs/site/docs/reference/api.md b/docs/site/docs/reference/api.md index 15ff60b6..0eaa99c8 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 its body 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. | @@ -63,6 +68,12 @@ Comment listing supports `cursor` and `limit`. Attachment listing supports 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 064348c1..4a2eb7ee 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,35 @@ 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. 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 54a8691c..323a5fd2 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 47931203..42eaab9a 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; 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 3b581b14..670f7a0f 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}` | 本文を編集するか、許可された状態遷移を行います。 | +| `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 します。 | @@ -63,7 +68,13 @@ comment listing は `cursor` と `limit` を受け付けます。attachment list 課題レスポンスには、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 d748febe..dda07603 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,34 @@ 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` は特定のリリースまたはプレリリースのタグをインストールします。 具体的な手順とサービス停止時の注意事項は、[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 d69593ce..02dea0ac 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 66a6ea67..b36c1a77 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`。終端状態では変更不可 | | 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` は終端状態です。 From 505404ff9dec54313d45a8abb15a50af4a6787d7 Mon Sep 17 00:00:00 2001 From: Jiro <j.code.public@gmail.com> Date: Fri, 14 Aug 2026 15:27:54 +0900 Subject: [PATCH 2/2] docs(site): clarify reference constraints Document change-request editing and list limits, profile restrictions for tq update, and the read-only TUI contract.\n\nAddresses PR review findings and keeps the English and Japanese references synchronized. Verified with the Docusaurus production build for both locales and git diff --check. --- docs/site/docs/reference/api.md | 4 +++- docs/site/docs/reference/cli-reference.md | 2 ++ docs/site/docs/reference/schema.md | 2 +- .../docusaurus-plugin-content-docs/current/reference/api.md | 4 +++- .../current/reference/cli-reference.md | 4 +++- .../current/reference/schema.md | 2 +- 6 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/site/docs/reference/api.md b/docs/site/docs/reference/api.md index 0eaa99c8..36c4eacd 100644 --- a/docs/site/docs/reference/api.md +++ b/docs/site/docs/reference/api.md @@ -51,7 +51,7 @@ Error responses use: | `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 its body or perform an allowed status transition. | +| `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. | @@ -66,6 +66,8 @@ 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. diff --git a/docs/site/docs/reference/cli-reference.md b/docs/site/docs/reference/cli-reference.md index 4a2eb7ee..6a94b1c2 100644 --- a/docs/site/docs/reference/cli-reference.md +++ b/docs/site/docs/reference/cli-reference.md @@ -101,6 +101,8 @@ Log services are `tracker` or `issue-tracker`, `orchestrator`, and `web`. `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). diff --git a/docs/site/docs/reference/schema.md b/docs/site/docs/reference/schema.md index 42eaab9a..4048c047 100644 --- a/docs/site/docs/reference/schema.md +++ b/docs/site/docs/reference/schema.md @@ -15,7 +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; status defaults to `open`; terminal requests are immutable | +| 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 | 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 670f7a0f..d6f60802 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 @@ -51,7 +51,7 @@ Issue Tracker は利用者向けの Tasq API です。プロジェクト、課 | `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}` | 本文を編集するか、許可された状態遷移を行います。 | +| `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 します。 | @@ -66,6 +66,8 @@ 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` です。 change request は、後続のエージェント実行で対応する追加作業を記録します。作成時の状態は `open` です。許可される状態遷移は `open` から `in_progress` または `canceled`、`in_progress` から `resolved` または `canceled` です。`resolved` と `canceled` は変更できません。取り消しは状態遷移として扱われ、物理削除のエンドポイントはありません。 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 dda07603..566efa48 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 @@ -93,12 +93,14 @@ create と update は、該当する場合に `--title`、`--description`、`--s ログ対象には `tracker` または `issue-tracker`、`orchestrator`、`web` を指定できます。 -`tq tui [--orchestrator-url URL]` はターミナルを必要とし、テキスト出力だけに対応します。課題、コメント、Artifact、実行状態を読み取りますが、変更リクエストは送信しません。`--orchestrator-url` を指定すると、`state.json` による orchestrator の検出を上書きできます。 +`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 直接実行コマンド 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 b36c1a77..48d949ad 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 @@ -15,7 +15,7 @@ Tasq は作成・更新時に、ストア層でエンティティのデータを | 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`。終端状態では変更不可 | +| 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 |