expedait-cli 0.3.0__tar.gz → 0.4.0__tar.gz

expedait_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+## 0.4.0
+
+Bring the CLI to parity with the hosted MCP server's write surface — agents can
+now create and adapt content, processes, and roles, not just read them. Every
+new command supports `--format json` and reports a per-op summary.
+
+### Added
+- **Deliverable writes** (mirror MCP `write_deliverable`):
+  - `deliverables write --ops @file.json` — ordered batch of `create` / `edit` /
+    `rename` / `save_version` / `set_state` ops, chainable with `id="$last"` or
+    named refs (`ref="x"` on create, `id="@x"` later). Pre-flight validates op
+    shape and reference ordering; ops stop on first failure (rest `skipped`) and
+    the command exits non-zero on partial failure.
+  - Ergonomic subcommands on top: `deliverables create`, `edit`, `rename`,
+    `save-version`, `set-state` (states: Not Started, In Progress, Review,
+    Approved, Completed, Final). `--content` / `--instructions` accept `@file`,
+    `-` (stdin), or a literal.
+- **`processes` command group** (mirror MCP `list_processes` / `get_process` /
+  `write_process`): `processes list`, `processes get PROCESS_ID` (full template
+  tree — phases, rows, deliverable-type cards, owner roles, objective
+  subprocesses), and `processes write --ops` (create/update/delete process,
+  phases, rows, deliverable types; `set_dependencies`; `set_owner_roles`). Named
+  refs, optional card layout with auto-placement (`after_type_id` / append),
+  role-name resolution, and an in-use delete guard (`confirm_in_use`).
+- **`roles` command group** (mirror MCP `list_roles` / `write_role`):
+  `roles list`, `roles create`, `roles update`, `roles delete`, and
+  `roles write --ops`.
+- **Context-file management** under the `context` group — manage the uploaded
+  files that feed a deliverable's (or objective's) LLM context: `context files`
+  (list), `context add` (upload; re-upload by name replaces), `context
+  file-content` (parsed text), `context download-file`, `context remove-file`,
+  and `context set-file --exclude/--include` (toggle a file in/out of the LLM
+  context). External source links remain web-app integration flows.
+- `expedait_cli/ops.py` — shared multi-op engine (`RefResolver`, `run_ops`,
+  `render_ops`) behind all three write surfaces, mirroring the MCP server's
+  `_common.py` run-ops scaffold.
+- `client.BackendError` + an op-safe request path so per-op failures are
+  captured and reported instead of aborting the whole command.
+- `deliverables types` — list deliverable types so you can find the `--type` id
+  that `deliverables create` needs.
+- `projects workspace [PROJECT_ID]` — deliverables grouped by phase (mirrors the
+  MCP `get_project_workspace` tool); the structure-aware view the flat
+  `deliverables list` can't give.
+
+### Fixed
+- `processes write` no longer crashes with an uncaught `KeyError` when an
+  `update_phase_row` op omits `position`; it now reports a clean per-op
+  `missing_field` error.
+- `--content` / `--instructions` / `--ops` with a missing or unreadable `@file`
+  now raise a clear usage error instead of leaking an `OSError` traceback. The
+  three duplicate readers were consolidated into one helper (`ops.read_value_arg`).
+- `projects download` no longer crashes. It passed a `fmt=` argument that the
+  client method never accepted (a `TypeError` on every run, hidden by a loosely
+  mocked test). The backend `/download` endpoint has no format parameter, so the
+  dead `--download-format` option was removed; the command always extracts the
+  markdown + images ZIP.
+
+## 0.3.0
+
+Adapt the CLI to the product's four-primitive domain model (objectives,
+deliverables, context, review).
+
+### Added
+- `deliverables` command group (`list`, `get`, `inspect`, `download`) — the
+  rename of `pages`, pointed at `/api/v1/deliverables/...`.
+- `deliverables get --include` — comma-separated section reads (`meta`,
+  `content`, `template`, `requirements`, `writer_instructions`, `dependencies`,
+  `external_context`, `score`, `comments`, `versions`), defaulting to `content`.
+  `meta` surfaces `parent_deliverable_id`.
+- `objectives overview DELIVERABLE_ID` — objective metadata plus its full
+  descendant tree.
+- `context get DELIVERABLE_ID` — read-only LLM context snapshot for a
+  deliverable.
+- `review` command group: `review issues DELIVERABLE_ID [--state open|muted|all]`
+  and `review mute ISSUE_ID [--note TEXT] [--unmute]`.
+- `comments create --agent-run-id` to link a comment to a build run.
+- `expedait-cli` console-script alias so `uvx expedait-cli …` keeps working.
+
+### Changed
+- `comments create` now resolves anchor offsets from the deliverable content;
+  only `--text` and `--selected-text` are required. `--start-offset` /
+  `--end-offset` remain available as explicit overrides.
+- Renamed `comments create --source-page-id` → `--source-deliverable-id`
+  (payload field `source_page_id` → `source_deliverable_id`).
+- `comments resolve` / `comments delete` now use the deliverable-scoped routes
+  `/api/v1/deliverables/{id}/comments/{comment_id}`.
+
+### Deprecated
+- The `pages` command group. `expedait pages …` still works for one release
+  (warns and forwards to `deliverables`) and will then be removed.

{expedait_cli-0.3.0 → expedait_cli-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: expedait-cli
-Version: 0.3.0
-Summary: CLI for Expedait project management — download specs, post comments
+Version: 0.4.0
+Summary: CLI for Expedait project management — read and write deliverables, processes, roles, and comments
 License-Expression: Apache-2.0
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -103,6 +103,7 @@ expedait auth logout      # Clear stored credentials
 ```bash
 expedait projects list                       # List all projects
 expedait projects get PROJECT_ID             # Get project details
+expedait projects workspace PROJECT_ID       # Deliverables grouped by phase (structure-aware view)
 expedait projects download PROJECT_ID        # Extract all deliverables to .expedait/context/
 expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custom directory
 ```
@@ -111,6 +112,7 @@ expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custo
 
 ```bash
 expedait deliverables list --project-id PROJECT_ID   # List deliverables in a project
+expedait deliverables types                           # List deliverable types (find the --type ID for create)
 expedait deliverables get DELIVERABLE_ID             # Print deliverable markdown content
 expedait deliverables get DELIVERABLE_ID --include meta,content,dependencies,score
 expedait deliverables inspect DELIVERABLE_ID         # Full context (content + comments + deps + lock)
@@ -123,6 +125,43 @@ expedait deliverables download DELIVERABLE_ID        # Extract to .expedait/cont
 `parent_deliverable_id` (non-null ⇒ this deliverable is a child nested under an
 objective).
 
+#### Writing deliverables
+
+Mirrors the MCP `write_deliverable` tool. Ergonomic subcommands cover the common
+cases; `write --ops` applies an ordered batch in one call.
+
+```bash
+expedait deliverables create --project P --type TYPE_ID --title "Vision" \
+  [--content @vision.md] [--parent-deliverable-id ID]   # create (content: @file, - for stdin, or literal)
+expedait deliverables edit DELIVERABLE_ID --content @body.md   # replace content (autosave, no version bump)
+expedait deliverables rename DELIVERABLE_ID --title "New title" # rename without touching content
+expedait deliverables save-version DELIVERABLE_ID --reason "checkpoint"  # explicit snapshot
+expedait deliverables set-state DELIVERABLE_ID --state "Review"          # transition workflow state
+```
+
+Valid states: `Not Started`, `In Progress`, `Review`, `Approved`, `Completed`,
+`Final`.
+
+For multi-step writes, `write --ops` takes a JSON ops array (`@file.json`, `-`
+for stdin, or inline). Each op is one of `create`, `edit`, `rename`,
+`save_version`, `set_state`. Chain ops on a freshly-created deliverable with
+`"id": "$last"` (the previous op's deliverable) or bind a name on create
+(`"ref": "x"`) and reference it later as `"id": "@x"`:
+
+```bash
+expedait deliverables write --ops @ops.json
+# ops.json:
+# [
+#   {"op": "create", "ref": "v", "project_id": 1, "deliverable_type_id": 3, "title": "Vision"},
+#   {"op": "edit", "id": "@v", "content": "# Product Vision\n..."},
+#   {"op": "set_state", "id": "@v", "state": "Review"}
+# ]
+```
+
+Ops run in order and stop on the first failure (the rest report `skipped`); the
+output reports per-op `{status: ok | error | skipped}`, and the command exits
+non-zero if any op failed.
+
 ### Objectives
 
 ```bash
@@ -135,6 +174,23 @@ expedait objectives overview DELIVERABLE_ID   # Objective metadata + full descen
 expedait context get DELIVERABLE_ID           # The LLM context snapshot for one deliverable
 ```
 
+A deliverable's (or objective's) context is built from dependency deliverables,
+linked external sources, and **uploaded context files**. The CLI manages the
+file half of that surface — attach reference docs an agent should write against,
+and toggle whether each one feeds the LLM context:
+
+```bash
+expedait context files DELIVERABLE_ID                 # List attached context files
+expedait context add DELIVERABLE_ID ./reference.md    # Upload a context file (re-upload by name replaces)
+expedait context file-content FILE_ID                 # Parsed text the file contributes to context
+expedait context download-file FILE_ID -o ./out.md    # Download a file's raw bytes
+expedait context set-file FILE_ID --exclude           # Exclude from LLM context (or --include)
+expedait context remove-file FILE_ID                  # Delete a context file
+```
+
+External source links (Notion, GitHub, etc.) are created through the web app's
+integration flows, not the CLI.
+
 ### Review
 
 ```bash
@@ -161,6 +217,56 @@ text in the deliverable to compute anchor offsets. Pass `--start-offset` and
 `--end-offset` to anchor explicitly (e.g. when the selected text appears more
 than once).
 
+### Processes (Process Designer)
+
+A *process* is a project type plus the template tree it owns: phases → rows →
+deliverable-type cards, dependency edges, owner roles, and objective
+subprocesses. Editing it reshapes **every** project instantiated from it.
+Mirrors the MCP `list_processes` / `get_process` / `write_process` tools.
+
+```bash
+expedait processes list                   # List processes (project types)
+expedait processes get PROCESS_ID         # Full template tree (phases, rows, cards, roles)
+expedait processes write --ops @ops.json  # Build or adapt a process in one call
+```
+
+`write --ops` ops: `create_process`, `update_process`, `duplicate_process`,
+`delete_process`, `create_phase`, `update_phase`, `delete_phase`,
+`create_phase_row`, `update_phase_row`, `delete_phase_row`,
+`create_deliverable_type`, `update_deliverable_type`, `delete_deliverable_type`,
+`set_dependencies`, `set_owner_roles`. Ops chain via named refs (`"ref": "x"` on
+a create op, `"@x"` later). Card layout is optional — omit `col_position` and
+cards auto-place (append, or just after `after_type_id`). `set_owner_roles`
+accepts role names or ids. Delete ops refuse an in-use template unless the op
+carries `"confirm_in_use": true`.
+
+```jsonc
+// ops.json — build a process end to end in one call
+[
+  {"op": "create_process", "ref": "p", "name": "Product Dev"},
+  {"op": "create_phase", "ref": "ph", "process_id": "@p", "name": "Discovery"},
+  {"op": "create_deliverable_type", "ref": "vision", "phase_id": "@ph", "name": "Vision"},
+  {"op": "create_deliverable_type", "ref": "prd", "phase_id": "@ph", "name": "PRD", "after_type_id": "@vision"},
+  {"op": "set_dependencies", "type_id": "@prd", "dependency_ids": ["@vision"]},
+  {"op": "set_owner_roles", "type_id": "@prd", "role_names": ["Product Manager"]}
+]
+```
+
+### Roles
+
+A *role* is a workspace project role — the owner-role pool assigned to
+deliverable types. A role's `instructions` is its LLM coaching persona. Mirrors
+the MCP `list_roles` / `write_role` tools.
+
+```bash
+expedait roles list                                       # List project roles
+expedait roles create --name "Product Manager" \          # Create (instructions: @file, -, or literal)
+  [--description "owns the roadmap"] [--instructions @pm.md]
+expedait roles update ROLE_ID --name "Lead PM"            # Update name/description/instructions
+expedait roles delete ROLE_ID                             # Delete a role
+expedait roles write --ops @ops.json                      # Batch (create_role/update_role/delete_role)
+```
+
 ### Global Options
 
 ```bash

{expedait_cli-0.3.0 → expedait_cli-0.4.0}/README.md

@@ -92,6 +92,7 @@ expedait auth logout      # Clear stored credentials
 ```bash
 expedait projects list                       # List all projects
 expedait projects get PROJECT_ID             # Get project details
+expedait projects workspace PROJECT_ID       # Deliverables grouped by phase (structure-aware view)
 expedait projects download PROJECT_ID        # Extract all deliverables to .expedait/context/
 expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custom directory
 ```
@@ -100,6 +101,7 @@ expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custo
 
 ```bash
 expedait deliverables list --project-id PROJECT_ID   # List deliverables in a project
+expedait deliverables types                           # List deliverable types (find the --type ID for create)
 expedait deliverables get DELIVERABLE_ID             # Print deliverable markdown content
 expedait deliverables get DELIVERABLE_ID --include meta,content,dependencies,score
 expedait deliverables inspect DELIVERABLE_ID         # Full context (content + comments + deps + lock)
@@ -112,6 +114,43 @@ expedait deliverables download DELIVERABLE_ID        # Extract to .expedait/cont
 `parent_deliverable_id` (non-null ⇒ this deliverable is a child nested under an
 objective).
 
+#### Writing deliverables
+
+Mirrors the MCP `write_deliverable` tool. Ergonomic subcommands cover the common
+cases; `write --ops` applies an ordered batch in one call.
+
+```bash
+expedait deliverables create --project P --type TYPE_ID --title "Vision" \
+  [--content @vision.md] [--parent-deliverable-id ID]   # create (content: @file, - for stdin, or literal)
+expedait deliverables edit DELIVERABLE_ID --content @body.md   # replace content (autosave, no version bump)
+expedait deliverables rename DELIVERABLE_ID --title "New title" # rename without touching content
+expedait deliverables save-version DELIVERABLE_ID --reason "checkpoint"  # explicit snapshot
+expedait deliverables set-state DELIVERABLE_ID --state "Review"          # transition workflow state
+```
+
+Valid states: `Not Started`, `In Progress`, `Review`, `Approved`, `Completed`,
+`Final`.
+
+For multi-step writes, `write --ops` takes a JSON ops array (`@file.json`, `-`
+for stdin, or inline). Each op is one of `create`, `edit`, `rename`,
+`save_version`, `set_state`. Chain ops on a freshly-created deliverable with
+`"id": "$last"` (the previous op's deliverable) or bind a name on create
+(`"ref": "x"`) and reference it later as `"id": "@x"`:
+
+```bash
+expedait deliverables write --ops @ops.json
+# ops.json:
+# [
+#   {"op": "create", "ref": "v", "project_id": 1, "deliverable_type_id": 3, "title": "Vision"},
+#   {"op": "edit", "id": "@v", "content": "# Product Vision\n..."},
+#   {"op": "set_state", "id": "@v", "state": "Review"}
+# ]
+```
+
+Ops run in order and stop on the first failure (the rest report `skipped`); the
+output reports per-op `{status: ok | error | skipped}`, and the command exits
+non-zero if any op failed.
+
 ### Objectives
 
 ```bash
@@ -124,6 +163,23 @@ expedait objectives overview DELIVERABLE_ID   # Objective metadata + full descen
 expedait context get DELIVERABLE_ID           # The LLM context snapshot for one deliverable
 ```
 
+A deliverable's (or objective's) context is built from dependency deliverables,
+linked external sources, and **uploaded context files**. The CLI manages the
+file half of that surface — attach reference docs an agent should write against,
+and toggle whether each one feeds the LLM context:
+
+```bash
+expedait context files DELIVERABLE_ID                 # List attached context files
+expedait context add DELIVERABLE_ID ./reference.md    # Upload a context file (re-upload by name replaces)
+expedait context file-content FILE_ID                 # Parsed text the file contributes to context
+expedait context download-file FILE_ID -o ./out.md    # Download a file's raw bytes
+expedait context set-file FILE_ID --exclude           # Exclude from LLM context (or --include)
+expedait context remove-file FILE_ID                  # Delete a context file
+```
+
+External source links (Notion, GitHub, etc.) are created through the web app's
+integration flows, not the CLI.
+
 ### Review
 
 ```bash
@@ -150,6 +206,56 @@ text in the deliverable to compute anchor offsets. Pass `--start-offset` and
 `--end-offset` to anchor explicitly (e.g. when the selected text appears more
 than once).
 
+### Processes (Process Designer)
+
+A *process* is a project type plus the template tree it owns: phases → rows →
+deliverable-type cards, dependency edges, owner roles, and objective
+subprocesses. Editing it reshapes **every** project instantiated from it.
+Mirrors the MCP `list_processes` / `get_process` / `write_process` tools.
+
+```bash
+expedait processes list                   # List processes (project types)
+expedait processes get PROCESS_ID         # Full template tree (phases, rows, cards, roles)
+expedait processes write --ops @ops.json  # Build or adapt a process in one call
+```
+
+`write --ops` ops: `create_process`, `update_process`, `duplicate_process`,
+`delete_process`, `create_phase`, `update_phase`, `delete_phase`,
+`create_phase_row`, `update_phase_row`, `delete_phase_row`,
+`create_deliverable_type`, `update_deliverable_type`, `delete_deliverable_type`,
+`set_dependencies`, `set_owner_roles`. Ops chain via named refs (`"ref": "x"` on
+a create op, `"@x"` later). Card layout is optional — omit `col_position` and
+cards auto-place (append, or just after `after_type_id`). `set_owner_roles`
+accepts role names or ids. Delete ops refuse an in-use template unless the op
+carries `"confirm_in_use": true`.
+
+```jsonc
+// ops.json — build a process end to end in one call
+[
+  {"op": "create_process", "ref": "p", "name": "Product Dev"},
+  {"op": "create_phase", "ref": "ph", "process_id": "@p", "name": "Discovery"},
+  {"op": "create_deliverable_type", "ref": "vision", "phase_id": "@ph", "name": "Vision"},
+  {"op": "create_deliverable_type", "ref": "prd", "phase_id": "@ph", "name": "PRD", "after_type_id": "@vision"},
+  {"op": "set_dependencies", "type_id": "@prd", "dependency_ids": ["@vision"]},
+  {"op": "set_owner_roles", "type_id": "@prd", "role_names": ["Product Manager"]}
+]
+```
+
+### Roles
+
+A *role* is a workspace project role — the owner-role pool assigned to
+deliverable types. A role's `instructions` is its LLM coaching persona. Mirrors
+the MCP `list_roles` / `write_role` tools.
+
+```bash
+expedait roles list                                       # List project roles
+expedait roles create --name "Product Manager" \          # Create (instructions: @file, -, or literal)
+  [--description "owns the roadmap"] [--instructions @pm.md]
+expedait roles update ROLE_ID --name "Lead PM"            # Update name/description/instructions
+expedait roles delete ROLE_ID                             # Delete a role
+expedait roles write --ops @ops.json                      # Batch (create_role/update_role/delete_role)
+```
+
 ### Global Options
 
 ```bash